mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
0ea1a427cc
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
716 lines
22 KiB
JSON
716 lines
22 KiB
JSON
{
|
||
"openapi": "3.0.1",
|
||
"info": {
|
||
"title": "Mintlify Index API",
|
||
"description": "为应用和代理搜索并获取技术文档与 Web 上下文。",
|
||
"version": "1.0.0"
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://leaves.mintlify.com/api/universal-search"
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/v1/context": {
|
||
"post": {
|
||
"operationId": "buildIndexContext",
|
||
"summary": "构建实现上下文",
|
||
"description": "搜索 Mintlify Index，并在 token 预算内组装带有来源引用的内容。当应用或代理需要通过一次请求获取可直接使用的上下文时，请使用此端点。",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ContextRequest"
|
||
},
|
||
"example": {
|
||
"query": "我应该如何在 Next.js 16 中配置缓存？",
|
||
"product": "Next.js",
|
||
"format": "txt",
|
||
"tokenBudget": 3000
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "上下文组装成功。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ContextResponse"
|
||
},
|
||
"example": {
|
||
"requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
|
||
"query": "我应该如何在 Next.js 16 中配置缓存？",
|
||
"response": "### 缓存与重新验证\n\n来源：https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\n使用本指南中介绍的当前缓存 API。\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": "搜索技术知识",
|
||
"description": "返回发布者维护的文档或 Web 中的排名结果。需要更多内容时，请将 Mintlify 结果 ID 或任意结果 URL 与 contents 端点搭配使用。",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SearchRequest"
|
||
},
|
||
"example": {
|
||
"query": "Next.js 16 缓存与重新验证",
|
||
"numResults": 5,
|
||
"text": {
|
||
"maxCharacters": 4000
|
||
},
|
||
"includeDomains": [
|
||
"nextjs.org"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "搜索成功完成。",
|
||
"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": "缓存与重新验证",
|
||
"text": "缓存是一种存储数据获取和其他计算结果的技术。",
|
||
"truncated": false,
|
||
"totalCharacters": 92,
|
||
"score": 0.91,
|
||
"source": "mintlify",
|
||
"siteName": "nextjs",
|
||
"breadcrumbs": [
|
||
"应用路由",
|
||
"开始使用"
|
||
],
|
||
"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": "获取结果内容",
|
||
"description": "获取搜索端点返回的 Mintlify 结果 ID 或结果 URL 对应的内容。一次请求最多可以在两个字段中包含 20 项。",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ContentsRequest"
|
||
},
|
||
"example": {
|
||
"ids": [
|
||
"nextjs:/docs/app/getting-started/caching-and-revalidating"
|
||
],
|
||
"query": "重新验证缓存的数据",
|
||
"maxCharacters": 12000
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"400": {
|
||
"description": "请求正文无效。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
},
|
||
"example": {
|
||
"error": "一个请求最多可以在 urls 和 ids 中引用 20 项"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"200": {
|
||
"description": "内容获取完成。请检查每个状态，以确定对应项目是否成功。",
|
||
"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": "缓存与重新验证",
|
||
"text": "# 缓存与重新验证\n\n使用重新验证 API 刷新缓存的数据。",
|
||
"truncated": false,
|
||
"totalCharacters": 78,
|
||
"score": 0,
|
||
"source": "mintlify",
|
||
"siteName": "nextjs",
|
||
"breadcrumbs": [
|
||
"应用路由",
|
||
"开始使用"
|
||
],
|
||
"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 密钥",
|
||
"description": "带有 `mint_us_` 前缀的 Mintlify Index API 密钥。"
|
||
}
|
||
},
|
||
"responses": {
|
||
"BadRequest": {
|
||
"description": "请求正文无效。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
},
|
||
"example": {
|
||
"error": "请求正文无效"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Unauthorized": {
|
||
"description": "API key 缺失或无效，或组织无权访问 Index REST API。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
},
|
||
"example": {
|
||
"error": "未授权"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Forbidden": {
|
||
"description": "API key 不允许该请求 IP。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
},
|
||
"example": {
|
||
"error": "该 API key 不允许此 IP 地址"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"RateLimited": {
|
||
"description": "组织超出速率限制。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
},
|
||
"example": {
|
||
"error": "超出速率限制。请稍后重试"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"InternalError": {
|
||
"description": "Index 无法完成请求。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"schemas": {
|
||
"ContextRequest": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"query",
|
||
"format"
|
||
],
|
||
"properties": {
|
||
"query": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "要研究的实现问题。"
|
||
},
|
||
"product": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "用作额外检索提示的产品或公司名称。"
|
||
},
|
||
"format": {
|
||
"type": "string",
|
||
"enum": [
|
||
"txt",
|
||
"json"
|
||
],
|
||
"description": "`response` 字符串的格式。`txt` 返回 Markdown 部分，`json` 返回包含结果项目的序列化 JSON 对象。"
|
||
},
|
||
"includeDomains": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "要纳入检索的域名。"
|
||
},
|
||
"excludeDomains": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "要从检索中排除的域名。"
|
||
},
|
||
"tokenBudget": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 6000,
|
||
"default": 3000,
|
||
"description": "输出 token 的最大数量。"
|
||
}
|
||
}
|
||
},
|
||
"ContextResponse": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"requestId",
|
||
"query",
|
||
"response",
|
||
"resultsCount",
|
||
"outputTokens"
|
||
],
|
||
"properties": {
|
||
"requestId": {
|
||
"type": "string",
|
||
"description": "请求的唯一标识符。"
|
||
},
|
||
"query": {
|
||
"type": "string",
|
||
"description": "请求中的原始查询。"
|
||
},
|
||
"response": {
|
||
"type": "string",
|
||
"description": "组装后的来源内容。对于 `txt` 请求，该值为 Markdown；对于 `json` 请求，该值为序列化 JSON。当没有内容适合 token 预算时，该字符串可以为空。"
|
||
},
|
||
"resultsCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"description": "响应中包含的来源片段数量。"
|
||
},
|
||
"outputTokens": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"description": "组装后响应中的 token 数量。"
|
||
}
|
||
}
|
||
},
|
||
"SearchRequest": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"query",
|
||
"numResults"
|
||
],
|
||
"properties": {
|
||
"query": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "搜索查询。"
|
||
},
|
||
"numResults": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 20,
|
||
"description": "要返回的最大结果数。"
|
||
},
|
||
"text": {
|
||
"default": false,
|
||
"description": "控制结果内容。设置为 `true` 可包含匹配的内容，设置为 `false` 可省略内容，或提供 `maxCharacters` 以包含截断后的内容。省略时默认为 `false`。",
|
||
"oneOf": [
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"maxCharacters"
|
||
],
|
||
"properties": {
|
||
"maxCharacters": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"description": "每个结果要包含的最大内容字符数。"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"includeDomains": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "要包含在搜索结果中的域名。"
|
||
},
|
||
"excludeDomains": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "要从搜索结果中排除的域名。"
|
||
}
|
||
}
|
||
},
|
||
"SearchResponse": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"requestId",
|
||
"results"
|
||
],
|
||
"properties": {
|
||
"requestId": {
|
||
"type": "string",
|
||
"description": "请求的唯一标识符。"
|
||
},
|
||
"results": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/SearchResult"
|
||
},
|
||
"description": "排名后的搜索结果。"
|
||
}
|
||
}
|
||
},
|
||
"SearchResult": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"id",
|
||
"url",
|
||
"title",
|
||
"text",
|
||
"score",
|
||
"source",
|
||
"siteName",
|
||
"breadcrumbs",
|
||
"publishedDate"
|
||
],
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "结果标识符。将 Mintlify 结果中的 ID 传入 contents 请求的 `ids` 字段。对于 Web 结果，请将结果 URL 传入 `urls`。"
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "规范来源 URL。"
|
||
},
|
||
"title": {
|
||
"type": "string",
|
||
"description": "来源标题。"
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"description": "请求时返回的匹配内容。否则为空字符串。"
|
||
},
|
||
"truncated": {
|
||
"type": "boolean",
|
||
"description": "返回的内容是否短于可用内容。"
|
||
},
|
||
"totalCharacters": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"description": "截断前的可用字符数（如果有）。"
|
||
},
|
||
"score": {
|
||
"type": "number",
|
||
"description": "相对相关性分数。contents 响应使用 `0`，因为它获取的是所选项目，而不是对结果进行排名。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"mintlify",
|
||
"web"
|
||
],
|
||
"description": "检索来源。"
|
||
},
|
||
"siteName": {
|
||
"type": "string",
|
||
"description": "文档站点或 Web 主机名。"
|
||
},
|
||
"breadcrumbs": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "结果的文档层级。"
|
||
},
|
||
"publishedDate": {
|
||
"type": "string",
|
||
"nullable": true,
|
||
"description": "来源提供时的发布日期，否则为 `null`。`search` 结果会将其规范化为完整的 ISO 8601 时间戳。通过 `urls` 获取的 `contents` 结果会原样传递来源的日期字符串，不进行规范化；该字符串可以是完整时间戳，也可以只是日期。"
|
||
}
|
||
}
|
||
},
|
||
"ContentsRequest": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"description": "至少提供一个 Mintlify 结果 ID 或结果 URL。你可以同时使用两个字段，总计最多 20 项。",
|
||
"anyOf": [
|
||
{
|
||
"required": [
|
||
"urls"
|
||
]
|
||
},
|
||
{
|
||
"required": [
|
||
"ids"
|
||
]
|
||
}
|
||
],
|
||
"properties": {
|
||
"urls": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"maxItems": 20,
|
||
"items": {
|
||
"type": "string",
|
||
"format": "uri"
|
||
},
|
||
"description": "要获取的结果 URL。对于 Web 结果，请使用此字段。"
|
||
},
|
||
"ids": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"maxItems": 20,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": "要获取的 Mintlify 结果 ID。"
|
||
},
|
||
"maxCharacters": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"description": "每个结果要返回的最大内容字符数。"
|
||
},
|
||
"query": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "当内容超过 `maxCharacters` 时，用于选择最相关部分的查询。"
|
||
}
|
||
}
|
||
},
|
||
"ContentsResponse": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"requestId",
|
||
"results",
|
||
"statuses"
|
||
],
|
||
"properties": {
|
||
"requestId": {
|
||
"type": "string",
|
||
"description": "请求的唯一标识符。"
|
||
},
|
||
"results": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/SearchResult"
|
||
},
|
||
"description": "成功获取的结果。"
|
||
},
|
||
"statuses": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/ContentStatus"
|
||
},
|
||
"description": "每个请求项目的获取状态。"
|
||
}
|
||
}
|
||
},
|
||
"ContentStatus": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"id",
|
||
"status"
|
||
],
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "请求的 ID 或 URL。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"success"
|
||
],
|
||
"description": "获取状态。"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"id",
|
||
"status",
|
||
"error"
|
||
],
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "请求的 ID 或 URL。"
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"error"
|
||
],
|
||
"description": "获取状态。"
|
||
},
|
||
"error": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"tag",
|
||
"httpStatusCode"
|
||
],
|
||
"properties": {
|
||
"tag": {
|
||
"type": "string",
|
||
"description": "机器可读的错误类别。"
|
||
},
|
||
"httpStatusCode": {
|
||
"type": "integer",
|
||
"nullable": true,
|
||
"description": "上游 HTTP 状态码（如果有）。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"Error": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"error"
|
||
],
|
||
"properties": {
|
||
"error": {
|
||
"type": "string",
|
||
"description": "错误消息。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|