API 指南

Context7 API 的身份验证、速率限制、最佳实践和集成指南

身份验证

所有 API 请求都需要使用 API 密钥进行身份验证。请在 Authorization 标头中包含你的 API 密钥：

Authorization: Bearer CONTEXT7_API_KEY

在 context7.com/dashboard 获取你的 API 密钥。了解更多关于创建和管理 API 密钥的信息。

速率限制

• 无 API 密钥: 低速率限制，无自定义配置
• 有 API 密钥: 基于你的计划提供更高的限制
• 在 控制台 查看当前使用情况和重置窗口。

当你超过速率限制时，API 会返回 429 状态代码：

{
  "error": "Too many requests",
  "status": 429
}

最佳实践

指定主题

使用 topic 参数获取更相关的结果并减少不必要的内容：

# 专注于路由特定的文档
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

缓存响应

将文档存储在本地以减少 API 调用并提高性能。文档更新相对不频繁，因此缓存几个小时或几天通常是合适的。

处理速率限制

针对速率限制错误实施指数退避：

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            # 遇到速率限制时使用指数退避等待
            time.sleep(2 ** attempt)
            continue

        return response

    raise Exception("Max retries exceeded")

使用特定版本

指定确切版本以在不同部署中保持结果一致：

# 锁定到特定版本
curl "https://context7.com/api/v2/docs/code/vercel/next.js/v15.1.8" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

使用分页获取更多结果

当你需要更多文档片段时，使用 page 参数获取更多页面。API 支持每个主题最多 10 页（总共 100 个片段）：

# 获取第一页
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=1" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

# 如果需要，获取下一页
curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing&page=2" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

响应包含分页元数据以帮助你导航：

{
  "snippets": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

提示：

• 使用特定主题以减少所需的总页数
• 在获取更多页面之前检查 hasNext
• 结合版本锁定以实现一致的分页

错误处理

Context7 API 使用标准的 HTTP 状态代码：

代码	描述	操作
200	成功	正常处理响应
401	未授权 - API 密钥无效或丢失	检查你的 API 密钥和身份验证标头
404	未找到 - 库或端点不存在	验证库 ID 或端点 URL
429	请求过多 - 超过速率限制	实施指数退避并重试
500	内部服务器错误	使用指数退避重试，如果持续存在请联系支持

错误响应格式

所有错误都返回具有以下字段的 JSON 对象：

{
  "error": "Error message describing what went wrong",
  "status": 429
}

SDK 和库

MCP Server (推荐)

Context7 Model Context Protocol (MCP) 服务器提供与 Claude 和其他 AI 工具的无缝集成：

npm install @upstash/context7-mcp

特性：

• 自动 API 密钥管理
• 内置缓存
• 类型安全的库解析
• 针对 AI 工作流进行了优化

请参阅 安装指南 获取详细的设置说明。

直接 API 集成

对于自定义集成或非 MCP 用例，直接使用 REST 端点。该 API 与语言无关，适用于任何 HTTP 客户端。

示例 (cURL):

curl "https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing" \
  -H "Authorization: Bearer CONTEXT7_API_KEY"

示例 (Python):

import requests

headers = {
    "Authorization": "Bearer CONTEXT7_API_KEY"
}

response = requests.get(
    "https://context7.com/api/v2/docs/code/vercel/next.js",
    headers=headers,
    params={"topic": "routing"}
)

docs = response.json()

示例 (JavaScript/Node.js):

const response = await fetch("https://context7.com/api/v2/docs/code/vercel/next.js?topic=routing", {
  headers: {
    Authorization: "Bearer CONTEXT7_API_KEY",
  },
});
const docs = await response.json();