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.

Note

A newer API v3 is in early development stages. Some improvements coming in v3 are:

  • Search API
  • Write access
  • Simpler URLs which use slugs instead of numeric IDs
  • Improved error reporting

If there are features you would like in v3, please get in touch in the issue tracker.

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",
    "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.

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:

  • The search API (/api/v2/search/)
  • 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.