# API Guide > Authentication, rate limits, best practices, and integration guides for the Context7 API ## Authentication All API requests require authentication using an API key. Include your API key in the `Authorization` header: ```bash Authorization: Bearer CONTEXT7_API_KEY ``` Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Learn more about [creating and managing API keys](/howto/api-keys). ## API Methods | Method | Endpoint | Description | |--------|----------|-------------| | [Search Documentation](/api-reference/search/search-documentation) | `GET /api/v3/search` | Find relevant documentation without resolving a library first | | [Search Library](/api-reference/search/search-for-libraries) | `GET /api/v2/libs/search` | Find libraries by name | | [Get Context](/api-reference/context/get-documentation-context) | `GET /api/v2/context` | Retrieve documentation snippets for a library | | [Refresh Library](/api-reference/refresh/refresh-a-library) | `POST /api/v1/refresh` | Refresh a library's documentation | | [Get Policies](/api-reference/policies/get-teamspace-policies) | `GET /api/v2/policies` | Retrieve teamspace policy configuration | | [Update Policies](/api-reference/policies/update-teamspace-policies) | `PATCH /api/v2/policies` | Update teamspace policies | | [Get Metrics](/api-reference/metrics/get-library-usage-metrics) | `GET /api/v2/libs/metrics` | Retrieve usage metrics for libraries | | [Add GitHub Repo](/api-reference/add-library/add-a-github-repository) | `POST /api/v2/add/repo/github` | Submit a GitHub repository for processing | | [Add GitLab Repo](/api-reference/add-library/add-a-gitlab-repository) | `POST /api/v2/add/repo/gitlab` | Submit a GitLab repository for processing | | [Add Bitbucket Repo](/api-reference/add-library/add-a-bitbucket-repository) | `POST /api/v2/add/repo/bitbucket` | Submit a Bitbucket repository for processing | | [Add Other Git Repo](/api-reference/add-library/add-from-other-git-providers) | `POST /api/v2/add/repo/git` | Submit a repository from any other Git provider | | [Add OpenAPI](/api-reference/add-library/add-an-openapi-specification-by-url) | `POST /api/v2/add/openapi` | Submit an OpenAPI spec | | [Upload OpenAPI](/api-reference/add-library/upload-an-openapi-specification-file) | `POST /api/v2/add/openapi-upload` | Upload an OpenAPI spec file | | [Add LLMs.txt](/api-reference/add-library/add-an-llmstxt-file) | `POST /api/v2/add/llmstxt` | Submit an llms.txt file | | [Add Website](/api-reference/add-library/add-a-website) | `POST /api/v2/add/website` | Submit a website for crawling | | [Add Confluence](/api-reference/add-library/add-a-confluence-space) | `POST /api/v2/add/confluence` | Submit a Confluence space | | [Add Notion](/api-reference/add-library/add-notion-pages) | `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](/api-reference/context/get-documentation-context) and [Refresh Library](/api-reference/refresh/refresh-a-library). Use `/owner/repo` for GitHub repositories, or `//` for other sources: | Source | Example library ID | |--------|--------------------| | GitHub repository | `/vercel/next.js` | | GitLab / Bitbucket / generic Git repo | `//` (same shape as GitHub) | | Website | `/websites/uploadcare` | | llms.txt source | `/llmstxt/` | | npm / package source | `/packages/` or `/npm/` | | Uploaded docs | `/docs/` | You can pin a specific version with either `/owner/repo/` or `/owner/repo@`: ``` /vercel/next.js/v15.1.8 /vercel/next.js@v15.1.8 ``` Don't know the ID for a library? Find it on [context7.com](https://context7.com) — the URL path of the library page **is** the ID. Or call [Search Library](/api-reference/search/search-for-libraries) 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. ```python import os import requests headers = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"} # Context7 selects the library and returns the best snippets response = 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. ```python import os import requests headers = {"Authorization": f"Bearer {os.environ['CONTEXT7_API_KEY']}"} # Find libraries that match the task search_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 library 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"}, ) 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]}...") ``` 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. For TypeScript SDK usage, see [Search](/sdks/ts/commands/search), [Search Library](/sdks/ts/commands/search-library), and [Get Context](/sdks/ts/commands/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](https://context7.com/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: ```bash # 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&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. ```bash 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: ```python 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: ```bash 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: ```json { "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](/sdks/ts/getting-started).