API Guide

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
Add Library	`POST /api/v2/add/repo/{provider}`	Submit a repository for processing
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

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_com, its ID is /websites/uploadcare_com. 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_com`
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/[email protected]

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 os
import requests

headers = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"}

# Step 1: Search for the library
search_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 context
context_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]}...")

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 question
curl "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 query
curl "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 shape
curl "https://context7.com/api/v2/context?libraryId=/websites/uploadcare_com&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 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:
            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/[email protected]&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.

Overview

How To

Enterprise

Security

Clients

SDKs

Agentic Tools

API Reference

Integrations

Resources

Authentication

API Methods

Library ID format

Complete Workflow Example

Rate Limits

Best Practices

Be Specific with Queries

Cache Responses

Handle Rate Limits

Use Specific Versions

Error Handling

SDK and Libraries

​Authentication

​API Methods

​Library ID format

​Complete Workflow Example

​Rate Limits

​Best Practices

​Be Specific with Queries

​Cache Responses

​Handle Rate Limits

​Use Specific Versions

​Error Handling

​SDK and Libraries

Authentication

API Methods

Library ID format

Complete Workflow Example

Rate Limits

Best Practices

Be Specific with Queries

Cache Responses

Handle Rate Limits

Use Specific Versions

Error Handling

SDK and Libraries