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: - 200 OK – no error
- 404 Not Found – There is no
Project
with this ID
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 (array) – Version objects for the given
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
orfalse
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: - 200 OK – no error
- 404 Not Found – There is no
Version
with this ID
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: - 200 OK – no error
- 404 Not Found – There is no
Build
with this ID
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.