API Guide - Context7 MCP

Authentication#

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer CONTEXT7_API_KEY

Get your API key at context7.com/dashboard. Learn more about creating and managing API keys.

API Methods#

Method	Endpoint	Description
Search Library	`GET /api/v2/libs/search`	Find libraries by name
Get Context	`GET /api/v2/context`	Retrieve documentation snippets for a library
Refresh Library	`POST /api/v1/refresh`	Refresh a library's documentation
Get Policies	`GET /api/v2/policies`	Retrieve teamspace policy configuration
Update Policies	`PATCH /api/v2/policies`	Update teamspace policies
Get Metrics	`GET /api/v2/libs/metrics`	Retrieve usage metrics for libraries
Add GitHub Repo	`POST /api/v2/add/repo/github`	Submit a GitHub repository for processing
Add GitLab Repo	`POST /api/v2/add/repo/gitlab`	Submit a GitLab repository for processing
Add Bitbucket Repo	`POST /api/v2/add/repo/bitbucket`	Submit a Bitbucket repository for processing
Add Other Git Repo	`POST /api/v2/add/repo/git`	Submit a repository from any other Git provider
Add OpenAPI	`POST /api/v2/add/openapi`	Submit an OpenAPI spec
Upload OpenAPI	`POST /api/v2/add/openapi-upload`	Upload an OpenAPI spec file
Add LLMs.txt	`POST /api/v2/add/llmstxt`	Submit an llms.txt file
Add Website	`POST /api/v2/add/website`	Submit a website for crawling
Add Confluence	`POST /api/v2/add/confluence`	Submit a Confluence space
Add Notion	`POST /api/v2/add/notion`	Submit Notion pages

Library ID format#

A library ID is the URL path of the library on context7.com. If the library page is at https://context7.com/websites/uploadcare, its ID is /websites/uploadcare. The same ID works for every endpoint that accepts a libraryId or libraryName — including Get Context and Refresh Library.

Use /owner/repo for GitHub repositories, or /<source>/<id> for other sources:

Source	Example library ID
GitHub repository	`/vercel/next.js`
GitLab / Bitbucket / generic Git repo	`/<owner>/<repo>` (same shape as GitHub)
Website	`/websites/uploadcare`
llms.txt source	`/llmstxt/<source>`
npm / package source	`/packages/<name>` or `/npm/<name>`
Uploaded docs	`/docs/<name>`

You can pin a specific version with either /owner/repo/<version> or /owner/repo@<version>:

/vercel/next.js/v15.1.8/vercel/next.js@v15.1.8

Tip

Don't know the ID for a library? Find it on context7.com — the URL path of the library page is the ID. Or call Search Library and use the id from the response.

Complete Workflow Example#

import osimport requestsheaders = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"}# Step 1: Search for the librarysearch_response = requests.get(    "https://context7.com/api/v2/libs/search",    headers=headers,    params={"libraryName": "react", "query": "I need to manage state"})data = search_response.json()best_match = data["results"][0]print(f"Found: {best_match['title']} ({best_match['id']})")# Step 2: Get documentation contextcontext_response = requests.get(    "https://context7.com/api/v2/context",    headers=headers,    params={"libraryId": best_match["id"], "query": "How do I use useState?", "type": "json"})docs = context_response.json()for snippet in docs["codeSnippets"]:    print(f"Title: {snippet['codeTitle']}")    for code in snippet["codeList"]:        print(f"Code: {code['code'][:200]}...")for info in docs["infoSnippets"]:    print(f"Content: {info['content'][:200]}...")

Info

For TypeScript SDK usage, see Search Library and Get Context.

Response Schemas#

Search response#

GET /api/v2/libs/search returns a JSON object:

{  "results": [    {      "id": "/facebook/react",      "title": "React",      "description": "The library for web and native user interfaces",      "branch": "main",      "lastUpdateDate": "2026-09-01T10:30:00.000Z",      "state": "finalized",      "totalTokens": 607822,      "totalSnippets": 3629,      "stars": 231000,      "trustScore": 10,      "benchmarkScore": 95.5,      "versions": ["v19.0.0", "v18.3.1"]    }  ],  "searchFilterApplied": false}

results — array of matching libraries ranked by relevance, using the Library ID format for id.
searchFilterApplied — true when the teamspace's public library access settings filtered the results (e.g. verified-only or a hand-picked list).
totalTokens is the total number of indexed tokens in the library's documentation, not the amount returned by a single context request — a context request returns a reranked subset of snippets.

Get Context#

GET /api/v2/context returns a ContextResponse JSON object:

Field	Type	Description
`codeSnippets`	array of `CodeSnippet`	Relevant code snippets
`infoSnippets`	array of `InfoSnippet`	Relevant prose documentation snippets
`rules`	object	Optional library-specific rules and guidelines (`global`, `libraryOwn`, `libraryTeam`, each an array of strings)

CodeSnippet — codeTitle, codeDescription, codeLanguage, codeTokens (token count for the snippet), codeId (URL to the source location), pageTitle (title of the documentation page), and codeList (the examples array) are all present. Snippets recovered from the dynamic source-code index additionally carry isDynamic and sourceFile.

The per-snippet examples array is codeList — not codeExamples. Each entry is a { "language", "code" } pair describing a single code example:

"codeList": [{ "language": "jsx", "code": "<App />" }]

InfoSnippet — content and contentTokens (token count for the content) are required; pageId (URL to the source page) and breadcrumb (navigation path) are returned when available.

{  "codeSnippets": [    {      "codeTitle": "Adding a Counter",      "codeDescription": "A minimal counter component",      "codeLanguage": "jsx",      "codeTokens": 150,      "codeId": "https://react.dev/reference/react/useState",      "pageTitle": "useState",      "codeList": [{ "language": "jsx", "code": "const [n, setN] = useState(0);" }]    }  ],  "infoSnippets": [    {      "pageId": "https://react.dev/reference/react/useState",      "breadcrumb": "Reference > React > useState",      "content": "useState is a React Hook that adds state...",      "contentTokens": 200    }  ]}

Rate Limits#

Without API key: Low rate limits and no custom configuration
With API key: Higher limits based on your plan
View current usage and reset windows in the dashboard.

When you exceed rate limits, the API returns a 429 status code with these headers:

Header	Description
`Retry-After`	Seconds until rate limit resets
`RateLimit-Limit`	Total request limit
`RateLimit-Remaining`	Remaining requests in window
`RateLimit-Reset`	Unix timestamp when limit resets

Best Practices#

Be Specific with Queries#

Use detailed, natural language queries for better results:

# Good - specific questioncurl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=How%20to%20implement%20authentication%20with%20middleware" \  -H "Authorization: Bearer CONTEXT7_API_KEY"# Less optimal - vague querycurl "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=auth" \  -H "Authorization: Bearer CONTEXT7_API_KEY"# Non-GitHub source (website) - same endpoint, same shapecurl "https://context7.com/api/v2/context?libraryId=/websites/uploadcare&query=image%20transformations" \  -H "Authorization: Bearer CONTEXT7_API_KEY"

Cache Responses#

Documentation updates are relatively infrequent, so caching responses for several hours or days reduces API calls and improves performance.

Handle Rate Limits#

Implement exponential backoff for rate limit errors:

import timeimport requestsdef 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:            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))            time.sleep(retry_after)            continue        return response    raise Exception("Max retries exceeded")

Use Specific Versions#

Pin to a specific version for consistent results. Both / and @ syntax are supported:

curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js/v15.1.8&query=app%20router" \  -H "Authorization: Bearer CONTEXT7_API_KEY"curl "https://context7.com/api/v2/context?libraryId=/vercel/next.js@v15.1.8&query=app%20router" \  -H "Authorization: Bearer CONTEXT7_API_KEY"

Error Handling#

The Context7 API uses standard HTTP status codes:

Code	Description	Action
200	Success	Process the response normally
202	Accepted - Library not finalized	Wait and retry later
301	Moved - Library redirected	Use the new library ID from `redirectUrl`
400	Bad Request - Invalid parameters	Check query parameters
401	Unauthorized - Invalid API key	Check your API key format (starts with `ctx7sk`)
403	Forbidden - Access denied	Check library access permissions or plan
404	Not Found - Library doesn't exist	Verify the library ID
409	Conflict - Resource already exists	The library has already been added
422	Unprocessable - Library too large/no code	Try a different library
429	Too Many Requests - Rate limit exceeded	Wait for `Retry-After` header, then retry
500	Internal Server Error	Retry with backoff
503	Service Unavailable - Search failed	Retry later
504	Gateway Timeout - Processing timed out	Retry later

All errors return a JSON object with error and message fields:

{  "error": "library_not_found",  "message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions."}

For 301 redirects, the response also includes a redirectUrl field pointing to the new library ID.

SDK and Libraries#

For TypeScript SDK installation and usage, see the Getting Started guide.