# Build implementation context (/api/search-index/context)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1756 · updated: 2026-09-23 -->
Related: [Mintlify Index REST API](/api/search-index/introduction.md), [Search technical knowledge](/api/search-index/search.md), [Get result contents](/api/search-index/contents.md)



`POST /v1/context`

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.

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "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."
            }
          }
        },
        "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": {
            "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."
              }
            }
          },
          "example": {
            "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
            "query": "How should I configure caching in Next.js 16?",
            "response": "### Caching and revalidating\n\nSource: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUse the current caching APIs described in this guide.\n\n--------------------------------",
            "resultsCount": 3,
            "outputTokens": 1842
          }
        }
      }
    },
    "400": {
      "description": "The request body is invalid.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Invalid request body"
          }
        }
      }
    },
    "401": {
      "description": "The API key is missing or invalid, or the organization does not have Index REST API access.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "The request IP is not allowed by the API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "IP address is not allowed for this API key"
          }
        }
      }
    },
    "429": {
      "description": "The organization exceeded a rate limit.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          },
          "example": {
            "error": "Rate limit exceeded. Please try again later"
          }
        }
      }
    },
    "500": {
      "description": "Index could not complete the request.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    }
  }
}
```