index-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify Index API",
    "description": "Search and retrieve technical documentation and web context for applications and agents.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://leaves.mintlify.com/api/universal-search"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/context": {
      "post": {
        "operationId": "buildIndexContext",
        "summary": "Build implementation context",
        "description": "Searches Mintlify Index and returns source-cited content assembled within a token budget. Use this endpoint when an application or agent needs ready-to-use context in one request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContextRequest"
              },
              "example": {
                "query": "How should I configure caching in Next.js 16?",
                "product": "Next.js",
                "format": "txt",
                "tokenBudget": 3000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Context assembled successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContextResponse"
                },
                "example": {
                  "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
                  "query": "How should I configure caching in Next.js 16?",
                  "response": "### Caching and revalidating\n\nSource: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUse the current caching APIs described in this guide.\n\n--------------------------------",
                  "resultsCount": 3,
                  "outputTokens": 1842
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/search": {
      "post": {
        "operationId": "searchIndex",
        "summary": "Search technical knowledge",
        "description": "Returns ranked results from publisher-maintained documentation or the web. Use Mintlify result IDs or any result URL with the contents endpoint when you need more content.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "Next.js 16 caching and revalidation",
                "numResults": 5,
                "text": {
                  "maxCharacters": 4000
                },
                "includeDomains": [
                  "nextjs.org"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search completed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8",
                  "results": [
                    {
                      "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
                      "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
                      "title": "Caching and revalidating",
                      "text": "Caching is a technique for storing the result of data fetching and other computations.",
                      "truncated": false,
                      "totalCharacters": 92,
                      "score": 0.91,
                      "source": "mintlify",
                      "siteName": "nextjs",
                      "breadcrumbs": [
                        "App Router",
                        "Getting started"
                      ],
                      "publishedDate": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/contents": {
      "post": {
        "operationId": "getIndexContents",
        "summary": "Get result contents",
        "description": "Retrieves content for Mintlify result IDs or result URLs returned by the search endpoint. A request can include up to 20 items across both fields.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentsRequest"
              },
              "example": {
                "ids": [
                  "nextjs:/docs/app/getting-started/caching-and-revalidating"
                ],
                "query": "revalidate cached data",
                "maxCharacters": 12000
              }
            }
          }
        },
        "responses": {
          "400": {
            "description": "The request body is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "A request may reference at most 20 items across urls and ids"
                }
              }
            }
          },
          "200": {
            "description": "Content retrieval completed. Check each status to determine whether its item succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentsResponse"
                },
                "example": {
                  "requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a",
                  "results": [
                    {
                      "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
                      "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating",
                      "title": "Caching and revalidating",
                      "text": "# Caching and revalidating\n\nUse revalidation APIs to refresh cached data.",
                      "truncated": false,
                      "totalCharacters": 78,
                      "score": 0,
                      "source": "mintlify",
                      "siteName": "nextjs",
                      "breadcrumbs": [
                        "App Router",
                        "Getting started"
                      ],
                      "publishedDate": null
                    }
                  ],
                  "statuses": [
                    {
                      "id": "nextjs:/docs/app/getting-started/caching-and-revalidating",
                      "status": "success"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Mintlify Index API key",
        "description": "Mintlify Index API key with the `mint_us_` prefix."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request body is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Invalid request body"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing or invalid, or the organization does not have Index REST API access.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Unauthorized"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The request IP is not allowed by the API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "IP address is not allowed for this API key"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The organization exceeded a rate limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Rate limit exceeded. Please try again later"
            }
          }
        }
      },
      "InternalError": {
        "description": "Index could not complete the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "ContextRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query",
          "format"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "Implementation question to research."
          },
          "product": {
            "type": "string",
            "minLength": 1,
            "description": "Product or company name to use as an additional retrieval hint."
          },
          "format": {
            "type": "string",
            "enum": [
              "txt",
              "json"
            ],
            "description": "Format of the `response` string. `txt` returns Markdown sections. `json` returns a serialized JSON object containing result items."
          },
          "includeDomains": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Domains to include in retrieval."
          },
          "excludeDomains": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Domains to exclude from retrieval."
          },
          "tokenBudget": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6000,
            "default": 3000,
            "description": "Maximum number of output tokens."
          }
        }
      },
      "ContextResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "query",
          "response",
          "resultsCount",
          "outputTokens"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique identifier for the request."
          },
          "query": {
            "type": "string",
            "description": "Original query from the request."
          },
          "response": {
            "type": "string",
            "description": "Assembled source content. The value is Markdown for `txt` requests and serialized JSON for `json` requests. The string can be empty when no content fits within the token budget."
          },
          "resultsCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of source snippets included in the response."
          },
          "outputTokens": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of tokens in the assembled response."
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query",
          "numResults"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "Search query."
          },
          "numResults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "Maximum number of results to return."
          },
          "text": {
            "default": false,
            "description": "Controls result content. Set to `true` to include matched content, `false` to omit it, or provide `maxCharacters` to include truncated content. When omitted, defaults to `false`.",
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "maxCharacters"
                ],
                "properties": {
                  "maxCharacters": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Maximum number of content characters to include per result."
                  }
                }
              }
            ]
          },
          "includeDomains": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Domains to include in search results."
          },
          "excludeDomains": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Domains to exclude from search results."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "results"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique identifier for the request."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            },
            "description": "Ranked search results."
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "url",
          "title",
          "text",
          "score",
          "source",
          "siteName",
          "breadcrumbs",
          "publishedDate"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Result identifier. Pass IDs from Mintlify results in the contents request's `ids` field. For web results, pass the result URL in `urls`."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical source URL."
          },
          "title": {
            "type": "string",
            "description": "Source title."
          },
          "text": {
            "type": "string",
            "description": "Matched content when requested. Otherwise, an empty string."
          },
          "truncated": {
            "type": "boolean",
            "description": "Whether the returned content is shorter than the available content."
          },
          "totalCharacters": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of available characters before truncation. Present when available."
          },
          "score": {
            "type": "number",
            "description": "Relative relevance score. Contents responses use `0` because they retrieve selected items rather than rank results."
          },
          "source": {
            "type": "string",
            "enum": [
              "mintlify",
              "web"
            ],
            "description": "Retrieval source."
          },
          "siteName": {
            "type": "string",
            "description": "Documentation site or web hostname."
          },
          "breadcrumbs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Documentation hierarchy for the result."
          },
          "publishedDate": {
            "type": "string",
            "nullable": true,
            "description": "Published date when the source provides one, otherwise `null`. `search` results normalize this to a full ISO 8601 timestamp. `contents` results retrieved by `urls` pass the source's original date string through unnormalized, which can be a full timestamp or a date-only string."
          }
        }
      },
      "ContentsRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "Provide at least one Mintlify result ID or result URL. You can combine both fields, with up to 20 items total.",
        "anyOf": [
          {
            "required": [
              "urls"
            ]
          },
          {
            "required": [
              "ids"
            ]
          }
        ],
        "properties": {
          "urls": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Result URLs to retrieve. Use this field for web results."
          },
          "ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Mintlify result IDs to retrieve."
          },
          "maxCharacters": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum number of content characters to return per result."
          },
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "Query used to select the most relevant sections when content exceeds `maxCharacters`."
          }
        }
      },
      "ContentsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "results",
          "statuses"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique identifier for the request."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            },
            "description": "Successfully retrieved results."
          },
          "statuses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContentStatus"
            },
            "description": "Retrieval status for each requested item."
          }
        }
      },
      "ContentStatus": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "status"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Requested ID or URL."
              },
              "status": {
                "type": "string",
                "enum": [
                  "success"
                ],
                "description": "Retrieval status."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "status",
              "error"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Requested ID or URL."
              },
              "status": {
                "type": "string",
                "enum": [
                  "error"
                ],
                "description": "Retrieval status."
              },
              "error": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "tag",
                  "httpStatusCode"
                ],
                "properties": {
                  "tag": {
                    "type": "string",
                    "description": "Machine-readable error category."
                  },
                  "httpStatusCode": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Upstream HTTP status code when available."
                  }
                }
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message."
          }
        }
      }
    }
  }
}