API v2

The Read the Docs API uses REST. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure.

Warning

API v2 is planned to be deprecated soon, though we have not yet set a time frame for deprecation yet. We will alert users with our plans when we do.

For now, API v2 is still used by some legacy application operations still, but we highly recommend Read the Docs users use API v3 instead.

Some improvements in API v3 are:

  • Token based authentication

  • Easier to use URLs which no longer use numerical ids

  • More common user actions are exposed through the API

  • Improved error reporting

See its full documentation at API v3.

Authentication and authorization

Requests to the Read the Docs public API are for public information only and do not require any authentication.

Resources

Projects

Projects are the main building block of Read the Docs. Projects are built when there are changes to the code and the resulting documentation is hosted and served by Read the Docs.

As an example, this documentation is part of the Docs project which has documentation at https://docs.readthedocs.io.

You can always view your Read the Docs projects in your project dashboard.

Project list

GET /api/v2/project/

Retrieve a list of all Read the Docs projects.

Example request:

curl https://readthedocs.org/api/v2/project/?slug=pip

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [PROJECTS]
}
Response JSON Object:

  • next (string) – URI for next set of Projects.

  • previous (string) – URI for previous set of Projects.

  • count (integer) – Total number of Projects.

  • results (array) – Array of Project objects.

Query Parameters:

  • slug (string) – Narrow the results by matching the exact project slug

Project details

GET /api/v2/project/(int: id)/

Retrieve details of a single project.

{
    "id": 6,
    "name": "Pip",
    "slug": "pip",
    "programming_language": "py",
    "default_version": "stable",
    "default_branch": "master",
    "repo_type": "git",
    "repo": "https://github.com/pypa/pip",
    "description": "Pip Installs Packages.",
    "language": "en",
    "documentation_type": "sphinx_htmldir",
    "canonical_url": "http://pip.pypa.io/en/stable/",
    "users": [USERS]
}
Response JSON Object:

  • id (integer) – The ID of the project

  • name (string) – The name of the project.

  • slug (string) – The project slug (used in the URL).

  • programming_language (string) – The programming language of the project (eg. “py”, “js”)

  • default_version (string) – The default version of the project (eg. “latest”, “stable”, “v3”)

  • default_branch (string) – The default version control branch

  • repo_type (string) – Version control repository of the project

  • repo (string) – The repository URL for the project

  • description (string) – An RST description of the project

  • language (string) – The language code of this project

  • documentation_type (string) – An RST description of the project

  • canonical_url (string) – The canonical URL of the default docs

  • users (array) – Array of User IDs who are maintainers of the project.

Status Codes:

Project versions

GET /api/v2/project/(int: id)/active_versions/

Retrieve a list of active versions (eg. “latest”, “stable”, “v1.x”) for a single project.

{
    "versions": [VERSION, VERSION, ...]
}
Response JSON Object:

  • versions (array) – Version objects for the given Project

See the Version detail call for the format of the Version object.

Versions

Versions are different versions of the same project documentation

The versions for a given project can be viewed in a project’s version screen. For example, here is the Pip project’s version screen.

Version list

GET /api/v2/version/

Retrieve a list of all Versions for all projects

{
    "count": 1000,
    "previous": null,
    "results": [VERSIONS],
    "next": "https://readthedocs.org/api/v2/version/?limit=10&offset=10"
}
Response JSON Object:

  • next (string) – URI for next set of Versions.

  • previous (string) – URI for previous set of Versions.

  • count (integer) – Total number of Versions.

  • results (array) – Array of Version objects.

Query Parameters:

  • project__slug (string) – Narrow to the versions for a specific Project

  • active (boolean) – Pass true or false to show only active or inactive versions. By default, the API returns all versions.

Version detail

GET /api/v2/version/(int: id)/

Retrieve details of a single version.

{
    "id": 1437428,
    "slug": "stable",
    "verbose_name": "stable",
    "built": true,
    "active": true,
    "type": "tag",
    "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
    "privacy_level": "public",
    "downloads": {
        "pdf": "//readthedocs.org/projects/pip/downloads/pdf/stable/",
        "htmlzip": "//readthedocs.org/projects/pip/downloads/htmlzip/stable/",
        "epub": "//readthedocs.org/projects/pip/downloads/epub/stable/"
    },
    "project": {PROJECT},
}
Response JSON Object:

  • id (integer) – The ID of the version

  • verbose_name (string) – The name of the version.

  • slug (string) – The version slug.

  • built (string) – Whether this version has been built

  • active (string) – Whether this version is still active

  • type (string) – The type of this version (typically “tag” or “branch”)

  • identifier (string) – A version control identifier for this version (eg. the commit hash of the tag)

  • downloads (array) – URLs to downloads of this version’s documentation

  • project (object) – Details of the Project for this version.

Status Codes:

Builds

Builds are created by Read the Docs whenever a Project has its documentation built. Frequently this happens automatically via a web hook but can be triggered manually.

Builds can be viewed in the build screen for a project. For example, here is Pip’s build screen.

Build list

GET /api/v2/build/

Retrieve details of builds ordered by most recent first

Example request:

curl https://readthedocs.org/api/v2/build/?project__slug=pip

Example response:

{
    "count": 100,
    "next": null,
    "previous": null,
    "results": [BUILDS]
}
Response JSON Object:

  • next (string) – URI for next set of Builds.

  • previous (string) – URI for previous set of Builds.

  • count (integer) – Total number of Builds.

  • results (array) – Array of Build objects.

Query Parameters:

  • project__slug (string) – Narrow to builds for a specific Project

  • commit (string) – Narrow to builds for a specific commit

Build detail

GET /api/v2/build/(int: id)/

Retrieve details of a single build.

{
    "id": 7367364,
    "date": "2018-06-19T15:15:59.135894",
    "length": 59,
    "type": "html",
    "state": "finished",
    "success": true,
    "error": "",
    "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30",
    "docs_url": "http://pip.pypa.io/en/latest/",
    "project": 13,
    "project_slug": "pip",
    "version": 3681,
    "version_slug": "latest",
    "commands": [
        {
            "description": "",
            "start_time": "2018-06-19T20:16:00.951959",
            "exit_code": 0,
            "build": 7367364,
            "command": "git remote set-url origin git://github.com/pypa/pip.git",
            "run_time": 0,
            "output": "",
            "id": 42852216,
            "end_time": "2018-06-19T20:16:00.969170"
        },
        ...
    ],
    ...
}
Response JSON Object:

  • id (integer) – The ID of the build

  • date (string) – The ISO-8601 datetime of the build.

  • length (integer) – The length of the build in seconds.

  • type (string) – The type of the build (one of “html”, “pdf”, “epub”)

  • state (string) – The state of the build (one of “triggered”, “building”, “installing”, “cloning”, or “finished”)

  • success (boolean) – Whether the build was successful

  • error (string) – An error message if the build was unsuccessful

  • commit (string) – A version control identifier for this build (eg. the commit hash)

  • docs_url (string) – The canonical URL of the build docs

  • project (integer) – The ID of the project being built

  • project_slug (string) – The slug for the project being built

  • version (integer) – The ID of the version of the project being built

  • version_slug (string) – The slug for the version of the project being built

  • commands (array) – Array of commands for the build with details including output.

Status Codes:

Some fields primarily used for UI elements in Read the Docs are omitted.

Embed

GET /api/v2/embed/

Retrieve HTML-formatted content from documentation page or section.

Warning

The content will be returned as is, without any sanitization or escaping. You should not include content from arbitrary projects, or projects you do not trust.

Example request:

curl https://readthedocs.org/api/v2/embed/?project=docs&version=latest&doc=features&path=features.html

or

curl https://readthedocs.org/api/v2/embed/?url=https://docs.readthedocs.io/en/latest/features.html

Example response:

{
    "content": [
        "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs..."
    ],
    "headers": [
        {
            "Read the Docs features": "#"
        },
        {
            "Automatic Documentation Deployment": "#automatic-documentation-deployment"
        },
        {
            "Custom Domains & White Labeling": "#custom-domains-white-labeling"
        },
        {
            "Versioned Documentation": "#versioned-documentation"
        },
        {
            "Downloadable Documentation": "#downloadable-documentation"
        },
        {
            "Full-Text Search": "#full-text-search"
        },
        {
            "Open Source and Customer Focused": "#open-source-and-customer-focused"
        }
    ],
    "url": "https://docs.readthedocs.io/en/latest/features",
    "meta": {
        "project": "docs",
        "version": "latest",
        "doc": "features",
        "section": "read the docs features"
    }
}
Response JSON Object:

  • content (string) – HTML content of the section.

  • headers (object) – section’s headers in the document.

  • url (string) – URL of the document.

  • meta (object) – meta data of the requested section.

Query Parameters:

  • project (string) – Read the Docs project’s slug.

  • doc (string) – document to fetch content from.

  • version (string) – optional Read the Docs version’s slug (default: latest).

  • section (string) – optional section within the document to fetch.

  • path (string) – optional full path to the document including extension.

  • url (string) – full URL of the document (and section) to fetch content from.

Note

You can call this endpoint by sending at least project and doc or url attribute.

Undocumented resources and endpoints

There are some undocumented endpoints in the API. These should not be used and could change at any time. These include:

  • Endpoints for returning footer and version data to be injected into docs. (/api/v2/footer_html)

  • Endpoints used for advertising (/api/v2/sustainability/)

  • Any other endpoints not detailed above.