# 搜索技术知识 (/zh/api/search-index/search) Related: [Mintlify Index REST API](/zh/api/search-index/introduction.md), [构建实现上下文](/zh/api/search-index/context.md), [获取结果内容](/zh/api/search-index/contents.md) `POST /v1/search` 返回发布者维护的文档或 Web 中的排名结果。需要更多内容时，请将 Mintlify 结果 ID 或任意结果 URL 与 contents 端点搭配使用。 ## OpenAPI ```json { "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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": "要从搜索结果中排除的域名。" } } }, "example": { "query": "Next.js 16 缓存与重新验证", "numResults": 5, "text": { "maxCharacters": 4000 }, "includeDomains": [ "nextjs.org" ] } } } }, "responses": { "200": { "description": "搜索成功完成。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "requestId", "results" ], "properties": { "requestId": { "type": "string", "description": "请求的唯一标识符。" }, "results": { "type": "array", "items": { "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` 结果会原样传递来源的日期字符串，不进行规范化；该字符串可以是完整时间戳，也可以只是日期。" } } }, "description": "排名后的搜索结果。" } } }, "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": { "description": "请求正文无效。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "description": "错误消息。" } } }, "example": { "error": "请求正文无效" } } } }, "401": { "description": "API key 缺失或无效，或组织无权访问 Index REST API。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "description": "错误消息。" } } }, "example": { "error": "未授权" } } } }, "403": { "description": "API key 不允许该请求 IP。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "description": "错误消息。" } } }, "example": { "error": "该 API key 不允许此 IP 地址" } } } }, "429": { "description": "组织超出速率限制。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "description": "错误消息。" } } }, "example": { "error": "超出速率限制。请稍后重试" } } } }, "500": { "description": "Index 无法完成请求。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "description": "错误消息。" } } } } } } } } ```