704 lines
22 KiB
JSON
704 lines
22 KiB
JSON
{
|
|
"openapi": "3.0.0",
|
|
"info": {
|
|
"title": "Context7 Public API",
|
|
"description": "The Context7 Public API provides programmatic access to library documentation and search functionality. Get up-to-date documentation and code examples for any library.",
|
|
"version": "2.0.0",
|
|
"contact": {
|
|
"name": "Context7 Support",
|
|
"url": "https://context7.com",
|
|
"email": "support@context7.com"
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://context7.com/api",
|
|
"description": "Production server"
|
|
}
|
|
],
|
|
"paths": {
|
|
"/v2/libs/search": {
|
|
"get": {
|
|
"summary": "Search for libraries",
|
|
"description": "Search for libraries by name with intelligent LLM-powered ranking based on your query context.",
|
|
"operationId": "searchLibraries",
|
|
"tags": ["Search"],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/LibraryNameParam"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/QueryParam"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Search results ranked by relevance",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SearchResponse"
|
|
},
|
|
"example": {
|
|
"results": [
|
|
{
|
|
"id": "/facebook/react",
|
|
"title": "React",
|
|
"description": "A JavaScript library for building user interfaces",
|
|
"branch": "main",
|
|
"lastUpdateDate": "2025-01-15T10:30:00.000Z",
|
|
"state": "finalized",
|
|
"totalTokens": 500000,
|
|
"totalSnippets": 2500,
|
|
"stars": 220000,
|
|
"trustScore": 10,
|
|
"benchmarkScore": 95.5,
|
|
"versions": ["v18.2.0", "v17.0.2"]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequestError"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimitError"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalServerError"
|
|
},
|
|
"503": {
|
|
"$ref": "#/components/responses/ServiceUnavailableError"
|
|
}
|
|
},
|
|
"security": [
|
|
{},
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/v2/context": {
|
|
"get": {
|
|
"summary": "Get documentation context",
|
|
"description": "Retrieve intelligent, LLM-reranked documentation context for natural language queries. Returns the most relevant code snippets and documentation for your specific question.",
|
|
"operationId": "getContext",
|
|
"tags": ["Context"],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/LibraryIdParam"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/QueryParam"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/TypeParam"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Documentation context",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ContextResponse"
|
|
},
|
|
"example": {
|
|
"codeSnippets": [
|
|
{
|
|
"codeTitle": "Middleware Authentication Example",
|
|
"codeDescription": "Shows how to implement authentication checks in Next.js middleware",
|
|
"codeLanguage": "typescript",
|
|
"codeTokens": 150,
|
|
"codeId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx#_snippet_0",
|
|
"pageTitle": "Middleware",
|
|
"codeList": [
|
|
{
|
|
"language": "typescript",
|
|
"code": "import { NextResponse } from 'next/server'\nimport type { NextRequest } from 'next/server'\n\nexport function middleware(request: NextRequest) {\n const token = request.cookies.get('token')\n if (!token) {\n return NextResponse.redirect(new URL('/login', request.url))\n }\n return NextResponse.next()\n}"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"infoSnippets": [
|
|
{
|
|
"pageId": "https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx",
|
|
"breadcrumb": "Routing > Middleware",
|
|
"content": "Middleware allows you to run code before a request is completed...",
|
|
"contentTokens": 200
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"text/plain": {
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "### Middleware Authentication Example\n\nSource: https://github.com/vercel/next.js/blob/canary/docs/middleware.mdx\n\nShows how to implement authentication checks in Next.js middleware\n\n```typescript\nimport { NextResponse } from 'next/server'\n...\n```"
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequestError"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/ForbiddenError"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFoundError"
|
|
},
|
|
"202": {
|
|
"$ref": "#/components/responses/AcceptedError"
|
|
},
|
|
"301": {
|
|
"$ref": "#/components/responses/RedirectError"
|
|
},
|
|
"422": {
|
|
"$ref": "#/components/responses/UnprocessableEntityError"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/UnauthorizedError"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimitError"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalServerError"
|
|
}
|
|
},
|
|
"security": [
|
|
{},
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "Get your API key at [context7.com/dashboard](https://context7.com/dashboard). Treat your API key like a password and store it securely."
|
|
}
|
|
},
|
|
"parameters": {
|
|
"LibraryNameParam": {
|
|
"name": "libraryName",
|
|
"in": "query",
|
|
"description": "Library name to search for (e.g., 'react', 'nextjs', 'express')",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 500
|
|
},
|
|
"example": "react"
|
|
},
|
|
"QueryParam": {
|
|
"name": "query",
|
|
"in": "query",
|
|
"description": "User's original question or task - used for intelligent relevance ranking",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 500
|
|
},
|
|
"example": "How to manage state with hooks"
|
|
},
|
|
"LibraryIdParam": {
|
|
"name": "libraryId",
|
|
"in": "query",
|
|
"description": "Context7-compatible library ID in format `/owner/repo` or `/owner/repo/version`",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 500,
|
|
"pattern": "^/[^/]+/[^/]+(/[^/]+)?$"
|
|
},
|
|
"examples": {
|
|
"basic": {
|
|
"summary": "Basic library ID",
|
|
"value": "/vercel/next.js"
|
|
},
|
|
"withVersion": {
|
|
"summary": "With specific version",
|
|
"value": "/vercel/next.js/v14.3.0"
|
|
}
|
|
}
|
|
},
|
|
"TypeParam": {
|
|
"name": "type",
|
|
"in": "query",
|
|
"description": "Response format type",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": ["json", "txt"],
|
|
"default": "txt"
|
|
},
|
|
"example": "json"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"Library": {
|
|
"type": "object",
|
|
"description": "Library metadata",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Library ID in format `/owner/repo`",
|
|
"example": "/vercel/next.js"
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display name of the library",
|
|
"example": "Next.js"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Short description",
|
|
"example": "The React Framework"
|
|
},
|
|
"branch": {
|
|
"type": "string",
|
|
"description": "Git branch being tracked",
|
|
"example": "canary"
|
|
},
|
|
"lastUpdateDate": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp of last update",
|
|
"example": "2025-01-15T10:30:00.000Z"
|
|
},
|
|
"state": {
|
|
"type": "string",
|
|
"enum": ["finalized", "initial", "processing", "error", "delete"],
|
|
"description": "Processing state of the library",
|
|
"example": "finalized"
|
|
},
|
|
"totalTokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens in documentation",
|
|
"example": 607822
|
|
},
|
|
"totalSnippets": {
|
|
"type": "integer",
|
|
"description": "Number of code snippets",
|
|
"example": 3629
|
|
},
|
|
"stars": {
|
|
"type": "integer",
|
|
"description": "GitHub stars count",
|
|
"example": 131745
|
|
},
|
|
"trustScore": {
|
|
"type": "integer",
|
|
"description": "Source reputation score (0-10)",
|
|
"minimum": 0,
|
|
"maximum": 10,
|
|
"example": 10
|
|
},
|
|
"benchmarkScore": {
|
|
"type": "number",
|
|
"description": "Quality indicator score (0-100)",
|
|
"minimum": 0,
|
|
"maximum": 100,
|
|
"example": 95.5
|
|
},
|
|
"versions": {
|
|
"type": "array",
|
|
"description": "Available version tags",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"example": ["v15.1.8", "v14.3.0"]
|
|
}
|
|
}
|
|
},
|
|
"SearchResponse": {
|
|
"type": "object",
|
|
"description": "Search results response",
|
|
"properties": {
|
|
"results": {
|
|
"type": "array",
|
|
"description": "Array of matching libraries ranked by relevance",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Library"
|
|
}
|
|
}
|
|
},
|
|
"required": ["results"]
|
|
},
|
|
"CodeSnippet": {
|
|
"type": "object",
|
|
"description": "A code snippet from library documentation",
|
|
"properties": {
|
|
"codeTitle": {
|
|
"type": "string",
|
|
"description": "Title of the code snippet"
|
|
},
|
|
"codeDescription": {
|
|
"type": "string",
|
|
"description": "Description of what the code does"
|
|
},
|
|
"codeLanguage": {
|
|
"type": "string",
|
|
"description": "Primary programming language"
|
|
},
|
|
"codeTokens": {
|
|
"type": "integer",
|
|
"description": "Token count for the snippet"
|
|
},
|
|
"codeId": {
|
|
"type": "string",
|
|
"description": "URL to source location"
|
|
},
|
|
"pageTitle": {
|
|
"type": "string",
|
|
"description": "Title of the documentation page"
|
|
},
|
|
"codeList": {
|
|
"type": "array",
|
|
"description": "Code examples in different languages",
|
|
"items": {
|
|
"$ref": "#/components/schemas/CodeExample"
|
|
}
|
|
}
|
|
},
|
|
"required": ["codeTitle", "codeDescription", "codeLanguage", "codeTokens", "codeId", "pageTitle", "codeList"]
|
|
},
|
|
"CodeExample": {
|
|
"type": "object",
|
|
"description": "A single code example",
|
|
"properties": {
|
|
"language": {
|
|
"type": "string",
|
|
"description": "Programming language"
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "The actual code content"
|
|
}
|
|
},
|
|
"required": ["language", "code"]
|
|
},
|
|
"InfoSnippet": {
|
|
"type": "object",
|
|
"description": "A documentation snippet",
|
|
"properties": {
|
|
"pageId": {
|
|
"type": "string",
|
|
"description": "URL to source page"
|
|
},
|
|
"breadcrumb": {
|
|
"type": "string",
|
|
"description": "Navigation breadcrumb path"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The documentation content"
|
|
},
|
|
"contentTokens": {
|
|
"type": "integer",
|
|
"description": "Token count for the content"
|
|
}
|
|
},
|
|
"required": ["content", "contentTokens"]
|
|
},
|
|
"ContextResponse": {
|
|
"type": "object",
|
|
"description": "Documentation context response",
|
|
"properties": {
|
|
"codeSnippets": {
|
|
"type": "array",
|
|
"description": "Relevant code snippets",
|
|
"items": {
|
|
"$ref": "#/components/schemas/CodeSnippet"
|
|
}
|
|
},
|
|
"infoSnippets": {
|
|
"type": "array",
|
|
"description": "Relevant documentation snippets",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InfoSnippet"
|
|
}
|
|
},
|
|
"rules": {
|
|
"type": "object",
|
|
"description": "Optional library-specific rules"
|
|
}
|
|
},
|
|
"required": ["codeSnippets", "infoSnippets"]
|
|
},
|
|
"Error": {
|
|
"type": "object",
|
|
"description": "Standard error response",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error code identifier"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable error message"
|
|
},
|
|
"status": {
|
|
"type": "integer",
|
|
"description": "HTTP status code"
|
|
}
|
|
},
|
|
"required": ["error"]
|
|
},
|
|
"RedirectErrorResponse": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"redirectUrl": {
|
|
"type": "string",
|
|
"description": "New location of the library"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"responses": {
|
|
"BadRequestError": {
|
|
"description": "Bad Request - Invalid input parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"examples": {
|
|
"validationError": {
|
|
"summary": "Validation error",
|
|
"value": {
|
|
"error": "validation_error",
|
|
"message": "Library name is required"
|
|
}
|
|
},
|
|
"invalidLibraryId": {
|
|
"summary": "Invalid library ID format",
|
|
"value": {
|
|
"error": "invalid_library_id",
|
|
"message": "Invalid library ID format. Expected: /owner/repo or /owner/repo/version"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ForbiddenError": {
|
|
"description": "Forbidden - Access denied",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "access_denied",
|
|
"message": "Access denied: Library /owner/repo is not included in your allowed libraries"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"NotFoundError": {
|
|
"description": "Not Found - Library or resource doesn't exist",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"examples": {
|
|
"libraryNotFound": {
|
|
"summary": "Library not found",
|
|
"value": {
|
|
"error": "library_not_found",
|
|
"message": "Library \"/owner/repo\" not found. Please check the library ID or your access permissions."
|
|
}
|
|
},
|
|
"tagNotFound": {
|
|
"summary": "Version tag not found",
|
|
"value": {
|
|
"error": "tag_not_found",
|
|
"message": "Tag \"v1.0.0\" not found for library \"/owner/repo\". Available tags: v2.0.0, v1.5.0"
|
|
}
|
|
},
|
|
"noSnippetsFound": {
|
|
"summary": "No snippets found",
|
|
"value": {
|
|
"error": "no_snippets_found",
|
|
"message": "Could not fetch documentation snippets from the library."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"InternalServerError": {
|
|
"description": "Internal Server Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "internal_server_error",
|
|
"message": "An internal error occurred while processing your request.",
|
|
"status": 500
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ServiceUnavailableError": {
|
|
"description": "Service Unavailable - Search failed",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "search_failed",
|
|
"message": "Search failed: Service temporarily unavailable"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"AcceptedError": {
|
|
"description": "Accepted - Library not yet finalized",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "library_not_finalized",
|
|
"message": "Library /owner/repo not finalized yet."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RedirectError": {
|
|
"description": "Moved Permanently - Library has been redirected",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RedirectErrorResponse"
|
|
},
|
|
"example": {
|
|
"error": "library_redirected",
|
|
"message": "Library /owner/repo has been redirected to this library: /new-owner/new-repo.",
|
|
"redirectUrl": "/new-owner/new-repo"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"UnprocessableEntityError": {
|
|
"description": "Unprocessable Entity - Library is too large or has no code",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"examples": {
|
|
"tooLarge": {
|
|
"summary": "Library too large",
|
|
"value": {
|
|
"error": "library_too_large",
|
|
"message": "Library /owner/repo is too large to process."
|
|
}
|
|
},
|
|
"noCode": {
|
|
"summary": "No code found",
|
|
"value": {
|
|
"error": "no_code_found",
|
|
"message": "Library /owner/repo has no or too few snippets found in documentation files."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"UnauthorizedError": {
|
|
"description": "Unauthorized - Invalid or missing API key",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "invalid_api_key",
|
|
"message": "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RateLimitError": {
|
|
"description": "Too Many Requests - Rate limit exceeded",
|
|
"headers": {
|
|
"Retry-After": {
|
|
"description": "Seconds until rate limit resets",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"RateLimit-Limit": {
|
|
"description": "Request limit",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"RateLimit-Remaining": {
|
|
"description": "Remaining requests",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"RateLimit-Reset": {
|
|
"description": "Unix timestamp when limit resets",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
},
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"example": {
|
|
"error": "Too Many Requests",
|
|
"message": "Rate limit exceeded. Please try again in 60 seconds."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [
|
|
{
|
|
"name": "Search",
|
|
"description": "Search for libraries in the Context7 database"
|
|
},
|
|
{
|
|
"name": "Context",
|
|
"description": "Retrieve documentation context for queries"
|
|
}
|
|
]
|
|
}
|