Build implementation context

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/context:
    post:
      summary: Build implementation context
      description: >-
        Searches Mintlify Index and returns source-cited content assembled
        within a token budget. Use this endpoint when an application or agent
        needs ready-to-use context in one request.
      operationId: buildIndexContext
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextRequest'
            example:
              query: How should I configure caching in Next.js 16?
              product: Next.js
              format: txt
              tokenBudget: 3000
      responses:
        '200':
          description: Context assembled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
              example:
                requestId: 7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c
                query: How should I configure caching in Next.js 16?
                response: >-
                  ### Caching and revalidating


                  Source:
                  https://nextjs.org/docs/app/getting-started/caching-and-revalidating


                  Use the current caching APIs described in this guide.


                  --------------------------------
                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'
components:
  schemas:
    ContextRequest:
      type: object
      additionalProperties: false
      required:
        - query
        - format
      properties:
        query:
          type: string
          minLength: 1
          description: Implementation question to research.
        product:
          type: string
          minLength: 1
          description: Product or company name to use as an additional retrieval hint.
        format:
          type: string
          enum:
            - txt
            - json
          description: >-
            Format of the `response` string. `txt` returns Markdown sections.
            `json` returns a serialized JSON object containing result items.
        includeDomains:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          description: Domains to include in retrieval.
        excludeDomains:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          description: Domains to exclude from retrieval.
        tokenBudget:
          type: integer
          minimum: 1
          maximum: 6000
          default: 3000
          description: Maximum number of output tokens.
    ContextResponse:
      type: object
      additionalProperties: false
      required:
        - requestId
        - query
        - response
        - resultsCount
        - outputTokens
      properties:
        requestId:
          type: string
          description: Unique identifier for the request.
        query:
          type: string
          description: Original query from the request.
        response:
          type: string
          description: >-
            Assembled source content. The value is Markdown for `txt` requests
            and serialized JSON for `json` requests. The string can be empty
            when no content fits within the token budget.
        resultsCount:
          type: integer
          minimum: 0
          description: Number of source snippets included in the response.
        outputTokens:
          type: integer
          minimum: 0
          description: Number of tokens in the assembled response.
    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.