context7/docs/openapi.json
Fahreddin Özcan eeddc37b27
CTX7-989: Update API Docs with v2 (#1333)
Co-authored-by: enesgules <abdullah.enes.gules@gmail.com>
2025-12-31 12:37:43 +03:00

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"
}
]
}