mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Kyan Yang
716 lines
22 KiB
JSON
716 lines
22 KiB
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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|