The Read the Docs API uses :abbr:`REST (Representational State Transfer)`. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure.
Note
A newer and better API v3 is ready to use. Some improvements coming in v3 are:
- Simpler URLs which use slugs
- Token based authentication
- Import a new project
- Activate a version
- Improved error reporting
See its full documentation at :doc:`/api/v3`.
Requests to the Read the Docs public API are for public information only and do not require any authentication.
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.
.. http:get:: /api/v2/project/
Retrieve a list of all Read the Docs projects.
**Example request**:
.. prompt:: bash $
curl https://readthedocs.org/api/v2/project/?slug=pip
**Example response**:
.. sourcecode:: js
{
"count": 1,
"next": null,
"previous": null,
"results": [PROJECTS]
}
:>json string next: URI for next set of Projects.
:>json string previous: URI for previous set of Projects.
:>json integer count: Total number of Projects.
:>json array results: Array of ``Project`` objects.
:query string slug: Narrow the results by matching the exact project slug
.. http:get:: /api/v2/project/(int:id)/
Retrieve details of a single project.
.. sourcecode:: js
{
"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]
}
:>json integer id: The ID of the project
:>json string name: The name of the project.
:>json string slug: The project slug (used in the URL).
:>json string programming_language: The programming language of the project (eg. "py", "js")
:>json string default_version: The default version of the project (eg. "latest", "stable", "v3")
:>json string default_branch: The default version control branch
:>json string repo_type: Version control repository of the project
:>json string repo: The repository URL for the project
:>json string description: An RST description of the project
:>json string language: The language code of this project
:>json string documentation_type: An RST description of the project
:>json string canonical_url: The canonical URL of the default docs
:>json array users: Array of ``User`` IDs who are maintainers of the project.
:statuscode 200: no error
:statuscode 404: There is no ``Project`` with this ID
.. http:get:: /api/v2/project/(int:id)/active_versions/
Retrieve a list of active versions (eg. "latest", "stable", "v1.x") for a single project.
.. sourcecode:: js
{
"versions": [VERSION, VERSION, ...]
}
:>json array versions: Version objects for the given ``Project``
See the :ref:`Version detail <api-version-detail>` call for the format of the ``Version`` object.
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.
.. http:get:: /api/v2/version/
Retrieve a list of all Versions for all projects
.. sourcecode:: js
{
"count": 1000,
"previous": null,
"results": [VERSIONS],
"next": "https://readthedocs.org/api/v2/version/?limit=10&offset=10"
}
:>json string next: URI for next set of Versions.
:>json string previous: URI for previous set of Versions.
:>json integer count: Total number of Versions.
:>json array results: Array of ``Version`` objects.
:query string project__slug: Narrow to the versions for a specific ``Project``
:query boolean active: Pass ``true`` or ``false`` to show only active or inactive versions.
By default, the API returns all versions.
.. http:get:: /api/v2/version/(int:id)/
Retrieve details of a single version.
.. sourcecode:: js
{
"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},
}
:>json integer id: The ID of the version
:>json string verbose_name: The name of the version.
:>json string slug: The version slug.
:>json string built: Whether this version has been built
:>json string active: Whether this version is still active
:>json string type: The type of this version (typically "tag" or "branch")
:>json string identifier: A version control identifier for this version (eg. the commit hash of the tag)
:>json array downloads: URLs to downloads of this version's documentation
:>json object project: Details of the ``Project`` for this version.
:statuscode 200: no error
:statuscode 404: There is no ``Version`` with this ID
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.
.. http:get:: /api/v2/build/
Retrieve details of builds ordered by most recent first
**Example request**:
.. prompt:: bash $
curl https://readthedocs.org/api/v2/build/?project__slug=pip
**Example response**:
.. sourcecode:: js
{
"count": 100,
"next": null,
"previous": null,
"results": [BUILDS]
}
:>json string next: URI for next set of Builds.
:>json string previous: URI for previous set of Builds.
:>json integer count: Total number of Builds.
:>json array results: Array of ``Build`` objects.
:query string project__slug: Narrow to builds for a specific ``Project``
:query string commit: Narrow to builds for a specific ``commit``
.. http:get:: /api/v2/build/(int:id)/
Retrieve details of a single build.
.. sourcecode:: js
{
"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"
},
...
],
...
}
:>json integer id: The ID of the build
:>json string date: The ISO-8601 datetime of the build.
:>json integer length: The length of the build in seconds.
:>json string type: The type of the build (one of "html", "pdf", "epub")
:>json string state: The state of the build (one of "triggered", "building", "installing", "cloning", or "finished")
:>json boolean success: Whether the build was successful
:>json string error: An error message if the build was unsuccessful
:>json string commit: A version control identifier for this build (eg. the commit hash)
:>json string docs_url: The canonical URL of the build docs
:>json integer project: The ID of the project being built
:>json string project_slug: The slug for the project being built
:>json integer version: The ID of the version of the project being built
:>json string version_slug: The slug for the version of the project being built
:>json array commands: Array of commands for the build with details including output.
:statuscode 200: no error
:statuscode 404: There is no ``Build`` with this ID
Some fields primarily used for UI elements in Read the Docs are omitted.
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.