Search technical knowledge

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/search:
    post:
      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.
      operationId: searchIndex
      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'
components:
  schemas:
    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.
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Error message.
  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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Mintlify Index API key
      description: Mintlify Index API key with the `mint_us_` prefix.