This subject folder contains the code for the Article API endpoints:

• /api/pagelist
• /api/pagelist/versions
• /api/pagelist/languages
• /api/article/body
• /api/article/meta

Related: The /llms.txt endpoint (middleware in src/frame/middleware/llms-txt.ts) provides AI-friendly content discovery using these APIs.

Article API endpoints allow consumers to query GitHub Docs for listings of current articles, and for specific article information.

The /api/article/meta endpoint powers hovercards, which provide a preview for internal links on <docs.github.com>.

The /api/article/body endpoint can serve markdown for both regular articles and autogenerated content (such as REST API documentation) using specialized transformers.

The /api/article endpoints return information about a page by pathname.

api/article/meta is highly cached, in JSON format.

The pagelist (/api/pagelist/:lang/:version) returns only canonical permalinks. The article API (/api/article, /api/article/body, /api/article/meta) transparently follows redirects—so URLs that don't appear in the pagelist (such as redirect_from aliases or old paths) may still return content.

When the article API resolves a redirect through the redirect table, the JSON response includes a redirectedFrom field containing the normalized pathname that was looked up (after trailing-slash removal and other standard normalization, not the raw originally-requested pathname). This field is only set for redirect-table lookups; it is not set for the bare / to /<lang> language rewrite. This lets consumers detect that the URL they requested is not canonical. The /api/article/body endpoint returns plain text, so redirectedFrom is not included in its response.

For autogenerated pages (REST, GraphQL, webhooks, landing pages, audit logs, etc), the Article API uses specialized transformers to convert the rendered content into markdown format. These transformers are located in src/article-api/transformers/ and use an extensible architecture.

To add a new transformer for other autogenerated content types:

1. Create a new transformer file implementing the PageTransformer interface
2. Register it in transformers/index.ts
3. Create a template in templates/ to configure how the transformer will organize the autogenerated content
4. The transformer will automatically be used by /api/article/body

For internal folks ask in the Docs Engineering slack channel.

For open source folks, please open a discussion in the public repository.

Get article metadata and content in a single object. Equivalent to calling /article/meta concatenated with /article/body.

Parameters:

• pathname (string) - Article path (e.g. '/en/get-started/article-name')
• [apiVersion] (string) - API version for REST pages (optional, defaults to latest)

Returns: (object) - JSON object with article metadata and content (meta and body keys)

Throws:

• (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
• (Error): 400 - If pathname or apiVersion parameters are invalid.
• (Error): 404 - If the path is valid, but the page couldn't be resolved.

Example:

❯ curl -s "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"
{
  "meta": {
    "title": "About GitHub and Git",
    "intro": "You can use GitHub and Git to collaborate on work.",
    "product": "Get started",
    "documentType": "article"
  },
  "body": "## About GitHub\n\nGitHub is a cloud-based platform where you can store, share, and work together with others to write code.\n\nStoring your code in a \"repository\" on GitHub allows you to:\n\n* **Showcase or share** your work.\n [...]"
}

Get the contents of an article's body.

Parameters:

• pathname (string) - Article path (e.g. '/en/get-started/article-name')
• [apiVersion] (string) - API version (optional, defaults to latest)

Returns: (string) - Article body content in markdown format.

Throws:

• (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
• (Error): 400 - If pathname or apiVersion parameters are invalid.
• (Error): 404 - If the path is valid, but the page couldn't be resolved.

Example:

❯ curl -s https://docs.github.com/api/article/body\?pathname=/en/get-started/start-your-journey/about-github-and-git
## About GitHub

GitHub is a cloud-based platform where you can store, share, and work together with others to write code.

Storing your code in a "repository" on GitHub allows you to:
[...]

Get metadata about an article.

Parameters:

• pathname (string) - Article path (e.g. '/en/get-started/article-name')

Returns: (object) - JSON object containing article metadata with title, intro, product, and documentType information.

Throws:

• (Error): 400 - If pathname parameter is invalid.
• (Error): 404 - If the path is valid, but the page couldn't be resolved.

Example:

❯ curl -s "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git"
{
  "title": "About GitHub and Git",
  "intro": "You can use GitHub and Git to collaborate on work.",
  "product": "Get started",
  "documentType": "article",
  "breadcrumbs": [
    {
      "href": "/en/get-started",
      "title": "Get started"
    },
    {
      "href": "/en/get-started/start-your-journey",
      "title": "Start your journey"
    },
    {
      "href": "/en/get-started/start-your-journey/about-github-and-git",
      "title": "About GitHub and Git"
    }
  ]
}

Get all available product versions for the docs site.

Returns: (object) - JSON object with version information

Example:

❯ curl -s https://docs.github.com/api/pagelist/versions | jq
{
  "versions": ["free-pro-team@latest", "enterprise-cloud@latest", "enterprise-server@3.19", ...],
  "ghesVersions": ["3.19", "3.18", "3.17", ...],
  "ghesLatest": "3.19",
  ...
}

Get all available languages for the docs site.

Returns: (object) - JSON object with language information

Example:

❯ curl -s https://docs.github.com/api/pagelist/languages | jq
{
  "languages": ["en", "es", "ja", "pt", "zh", "ru", "fr", "ko", "de"],
  "allLanguages": { ... }
}

A list of pages available for a fully qualified path containing the target language and product version.

Parameters:

• lang (string) - Path parameter for language code (e.g. 'en')
• productVersion (string) - Path parameter for product version (e.g. 'free-pro-team@latest')

Returns: (string) - List of paths matching the language and version

Throws:

• (Error): 400 - If language or version parameters are invalid. Reason is given in the error message.

Example:

❯ curl -s https://docs.github.com/api/pagelist/en/free-pro-team@latest
/en
/en/search
/en/get-started
/en/get-started/start-your-journey
/en/get-started/start-your-journey/about-github-and-git
[...]