Get result contents

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/contents:
    post:
      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.
      operationId: getIndexContents
      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:
        '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

                      Use 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
        '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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    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.
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Error message.
    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.
    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.
  responses:
    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.