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 Documentation	`GET /api/v3/search`	Find relevant documentation without resolving a library first
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.

Search documentation in one request#

The Search API is the simplest way to retrieve documentation. You provide a question, and Context7 selects relevant libraries before searching and reranking their snippets.

If no documentation matches, Search returns 404 no_documentation_found; treat it as an empty result. A temporary search failure returns 503 search_failed and can be retried.

import osimport requestsheaders = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"}# Context7 selects the library and returns the best snippetsresponse = requests.get(    "https://context7.com/api/v3/search",    headers=headers,    params={        "query": "How do I stream an OpenAI response from a Next.js route?",        "library": ["Next.js", "OpenAI"],        "language": "TypeScript",        "type": "json",    },)response.raise_for_status()docs = response.json()for snippet in docs["codeSnippets"]:    print(f"Library: {snippet['libraryId']}")    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]}...")

Library hints are optional and do not need to be exact. You can provide up to four names or exact Context7 library IDs. Use version with at least one library hint, and use language when you want language-specific examples to rank higher.

Choose a library yourself#

Use Search Library followed by Get Context when your application needs to inspect or choose a specific documentation source.

import osimport requestsheaders = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"}# Find libraries that match the tasksearch_response = requests.get(    "https://context7.com/api/v2/libs/search",    headers=headers,    params={"libraryName": "react", "query": "I need to manage state"},)search_response.raise_for_status()best_match = search_response.json()["results"][0]print(f"Found: {best_match['title']} ({best_match['id']})")# Request documentation from the selected librarycontext_response = requests.get(    "https://context7.com/api/v2/context",    headers=headers,    params={"libraryId": best_match["id"], "query": "How do I use useState?", "type": "json"},)context_response.raise_for_status()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

Each Search API call counts as one request. The two-step flow makes two API calls when it searches for a library and then retrieves its documentation.

Info

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

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"

Add hints only when they provide useful context#

Start with only the question when the relevant library is clear from the task. Add library hints when a name is ambiguous or when the answer needs documentation from more than one product.

curl -G "https://context7.com/api/v3/search" \  -H "Authorization: Bearer CONTEXT7_API_KEY" \  --data-urlencode "query=How do I stream an OpenAI response from a Next.js route?" \  --data-urlencode "library=Next.js" \  --data-urlencode "library=OpenAI" \  --data-urlencode "language=TypeScript"

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.