> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索技术知识

> 在 Mintlify Index 中搜索排名后的技术文档和 Web 结果。



## OpenAPI

````yaml zh/index-openapi.json POST /v1/search
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/search:
    post:
      summary: 搜索技术知识
      description: >-
        返回发布者维护的文档或 Web 中的排名结果。需要更多内容时，请将 Mintlify 结果 ID 或任意结果 URL 与 contents
        端点搭配使用。
      operationId: searchIndex
      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'
components:
  schemas:
    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` 结果会原样传递来源的日期字符串，不进行规范化；该字符串可以是完整时间戳，也可以只是日期。
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: 错误消息。
  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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Mintlify Index API 密钥
      description: 带有 `mint_us_` 前缀的 Mintlify Index API 密钥。

````

## Related topics

- [Mintlify Index REST API](/docs/zh/api/search-index/introduction.md)
- [指南](/docs/zh/guides/index.md)
- [Mintlify Index](/docs/zh/search-index/index.md)