# 构建实现上下文 (/zh/api/search-index/context)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1530 · updated: 2026-09-23 -->
Related: [Mintlify Index REST API](/zh/api/search-index/introduction.md), [搜索技术知识](/zh/api/search-index/search.md), [获取结果内容](/zh/api/search-index/contents.md)



`POST /v1/context`

搜索 Mintlify Index，并在 token 预算内组装带有来源引用的内容。当应用或代理需要通过一次请求获取可直接使用的上下文时，请使用此端点。

## 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": "要研究的实现问题。"
            },
            "product": {
              "type": "string",
              "minLength": 1,
              "description": "用作额外检索提示的产品或公司名称。"
            },
            "format": {
              "type": "string",
              "enum": [
                "txt",
                "json"
              ],
              "description": "`response` 字符串的格式。`txt` 返回 Markdown 部分，`json` 返回包含结果项目的序列化 JSON 对象。"
            },
            "includeDomains": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "要纳入检索的域名。"
            },
            "excludeDomains": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "要从检索中排除的域名。"
            },
            "tokenBudget": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6000,
              "default": 3000,
              "description": "输出 token 的最大数量。"
            }
          }
        },
        "example": {
          "query": "我应该如何在 Next.js 16 中配置缓存？",
          "product": "Next.js",
          "format": "txt",
          "tokenBudget": 3000
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "上下文组装成功。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "requestId",
              "query",
              "response",
              "resultsCount",
              "outputTokens"
            ],
            "properties": {
              "requestId": {
                "type": "string",
                "description": "请求的唯一标识符。"
              },
              "query": {
                "type": "string",
                "description": "请求中的原始查询。"
              },
              "response": {
                "type": "string",
                "description": "组装后的来源内容。对于 `txt` 请求，该值为 Markdown；对于 `json` 请求，该值为序列化 JSON。当没有内容适合 token 预算时，该字符串可以为空。"
              },
              "resultsCount": {
                "type": "integer",
                "minimum": 0,
                "description": "响应中包含的来源片段数量。"
              },
              "outputTokens": {
                "type": "integer",
                "minimum": 0,
                "description": "组装后响应中的 token 数量。"
              }
            }
          },
          "example": {
            "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c",
            "query": "我应该如何在 Next.js 16 中配置缓存？",
            "response": "### 缓存与重新验证\n\n来源：https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\n使用本指南中介绍的当前缓存 API。\n\n--------------------------------",
            "resultsCount": 3,
            "outputTokens": 1842
          }
        }
      }
    },
    "400": {
      "description": "请求正文无效。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          },
          "example": {
            "error": "请求正文无效"
          }
        }
      }
    },
    "401": {
      "description": "API key 缺失或无效，或组织无权访问 Index REST API。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          },
          "example": {
            "error": "未授权"
          }
        }
      }
    },
    "403": {
      "description": "API key 不允许该请求 IP。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          },
          "example": {
            "error": "该 API key 不允许此 IP 地址"
          }
        }
      }
    },
    "429": {
      "description": "组织超出速率限制。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          },
          "example": {
            "error": "超出速率限制。请稍后重试"
          }
        }
      }
    },
    "500": {
      "description": "Index 无法完成请求。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          }
        }
      }
    }
  }
}
```