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.

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.