Context7 Library ID Format and Version Specification Guide

Context7 library IDs follow a strict path-like syntax using /owner/repo for latest versions and /owner/repo/version for specific releases, validated by the regex pattern ^/[^/]+/[^/]+(/[^/]+)?$.

The Context7 library ID format is a standardized string syntax that uniquely identifies documentation sets within the Context7 ecosystem. Understanding this format is essential when using the queryDocs tool or the REST API to retrieve version-specific documentation for open-source libraries.

Understanding the Context7 Library ID Syntax

The Base Format (/owner/repo)

Every Context7 library ID begins with a forward slash and contains two required segments separated by slashes:

/owner/repo

• owner — The organization or user that owns the repository (e.g., vercel, facebook, reactjs).
• repo — The name of the library or project (e.g., next.js, react, react.dev).

When you omit the version segment, Context7 automatically returns documentation for the latest stable release of that library.

Adding Version Segments (/owner/repo/version)

To query documentation for a specific release, append a third segment containing the exact version tag:

/owner/repo/version

• version — Any valid version tag that exists for the library (e.g., v14.3.0, 19.0.0, v0.76.0).

This three-segment format ensures you receive documentation that matches the exact API surface of the specified release, which is critical when maintaining projects locked to older versions.

Validation Pattern

The API enforces this syntax using a regular expression defined in the OpenAPI specification at docs/openapi.json (lines 20-27):

^/[^/]+/[^/]+(/[^/]+)?$

This pattern ensures:

• The ID starts with /
• Contains at least two non-empty segments (owner and repo)
• Optionally accepts a third segment for versions
• Rejects trailing slashes or empty segments

How to Specify Versions in Context7 Queries

Latest Stable vs. Specific Versions

When using the queryDocs tool implemented in packages/tools-ai-sdk/src/tools/query-docs.ts (lines 40-45), you control version scope through the libraryId parameter:

• Latest docs: Use /owner/repo to retrieve the most recent stable documentation
• Version-specific docs: Use /owner/repo/version to target a particular release

Omitting the version segment is the default behavior for most AI SDK implementations, allowing agents to always access current documentation unless historical context is specifically required.

Version Resolution Workflow

For dynamic version discovery, the resolveLibraryId tool (documented in docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx) returns available versions alongside the canonical library ID. This enables workflows where:

1. The AI resolves the library name to its canonical ID
2. Receives a list of available versions
3. Selects the appropriate version based on project requirements
4. Queries documentation using the full three-segment ID

Practical Code Examples

Fetching Latest Documentation

import { queryDocs } from "@upstash/context7-tools-ai-sdk";

const result = await queryDocs().execute({
  libraryId: "/vercel/next.js",      // No version segment = latest stable
  query: "How do I enable image optimization?",
});
console.log(result);

Retrieving Specific Version Documentation

import { queryDocs } from "@upstash/context7-tools-ai-sdk";

const result = await queryDocs().execute({
  libraryId: "/vercel/next.js/v14.3.0", // Version-specific ID
  query: "What is the new routing API?",
});
console.log(result);

Dynamic Version Resolution and Querying

import {
  resolveLibraryId,
  queryDocs,
} from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const { text, toolCalls } = await generateText({
  model: openai("gpt-4o"),
  prompt: "Give me the migration guide from React 17 to React 18",
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  // Workflow:
  // 1. Calls resolveLibraryId → receives `/reactjs/react.dev` and version list
  // 2. Selects version `/reactjs/react.dev/v18.0.0`
  // 3. Calls queryDocs with version-specific ID
  stopWhen: stepCountIs(5),
});

console.log(text);

Common Library ID Patterns

The following table illustrates valid Context7 library ID formats for popular repositories:

Goal	Library ID	Structure
Latest Next.js docs	/vercel/next.js	/owner/repo
Next.js v14.3.0	/vercel/next.js/v14.3.0	/owner/repo/version
Latest React	/facebook/react	/owner/repo
React 18.2.0	/facebook/react/v18.2.0	/owner/repo/version
React Native v0.76.0	/facebook/react-native/v0.76.0	/owner/repo/version

Troubleshooting Invalid Library IDs

If you encounter "Library Not Found" errors when querying Context7, verify your ID format against the troubleshooting guidelines in docs/resources/troubleshooting.mdx. Common issues include:

• Missing leading forward slash
• Using repository URLs instead of the /owner/repo format
• Including invalid characters in version tags
• Specifying versions that do not exist in the Context7 index

The validation regex ^/[^/]+/[^/]+(/[^/]+)?$ enforces strict segment boundaries, ensuring consistent parsing across all API endpoints.

Summary

• Context7 library ID format requires a leading slash followed by two or three path segments: /owner/repo for latest versions or /owner/repo/version for specific releases.
• The API validates IDs using the regex pattern ^/[^/]+/[^/]+(/[^/]+)?$ defined in docs/openapi.json.
• Omitting the version segment returns the latest stable documentation; appending a version tag scopes queries to that specific release.
• Use resolveLibraryId to discover available versions dynamically before constructing version-specific queries with queryDocs.

Frequently Asked Questions

What happens if I omit the version segment in a Context7 library ID?

If you omit the version segment and use only /owner/repo, Context7 automatically returns documentation for the latest stable version of that library. This is the recommended approach when you want current API documentation without hardcoding specific version numbers.

How do I find the correct version tag to use in a Context7 library ID?

Use the resolveLibraryId tool to fetch the canonical library ID along with a list of available versions. According to the implementation in docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx, this tool returns version tags exactly as they exist in the Context7 index, allowing you to select the appropriate tag for your query.

Why am I getting a "Library Not Found" error with a valid GitHub URL?

Context7 library IDs do not use full GitHub URLs. The API expects the specific path format /owner/repo or /owner/repo/version as defined in docs/openapi.json. Ensure your ID starts with a forward slash, contains no protocol prefixes (like https://), and matches the validation regex ^/[^/]+/[^/]+(/[^/]+)?$.

Can I use semantic version ranges like "^1.0.0" in Context7 library IDs?

No, Context7 requires exact version tags in the third segment of the library ID. The regex pattern in docs/openapi.json enforces literal string matching for version segments. You must specify the complete version tag exactly as it appears in the library's documentation set (e.g., v14.3.0 or 19.0.0), without range operators or wildcards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}