API v3¶
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.
Table of contents
Authentication and authorization¶
Requests to the Read the Docs public API are for public and private information. All endpoints require authentication.
Token¶
The Authorization HTTP header can be specified with Token <your-access-token>
to authenticate as a user and have the same permissions that the user itself.
Session¶
警告
Authentication via session is not enabled yet.
Session authentication is allowed on very specific endpoints, to allow hitting the API when reading documentation.
When a user is trying to authenticate via session, CSRF check is performed.
Resources¶
This section shows all the resources that are currently available in APIv3. There are some URL attributes that applies to all of these resources:
| ?fields=: | Specify which fields are going to be returned in the response. |
|---|---|
| ?omit=: | Specify which fields are going to be omitted from the response. |
| ?expand=: | Some resources allow to expand/add extra fields on their responses (see Project details for example). |
注釈
If you are using Read the Docs for Business take into account that you will need to replace https://readthedocs.org/ by https://readthedocs.com/ in all the URLs used in the following examples.
Versions¶
Versions are different versions of the same project documentation.
The versions for a given project can be viewed in a project's version page. For example, here is the Pip project's version page. See /versions for more information.
Versions listing¶
Version detail¶
Version update¶
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 page for a project. For example, here is Pip's build page. See /builds for more information.
Build details¶
Builds listing¶
Build triggering¶
Subprojects¶
Projects can be configured in a nested manner, by configuring a project as a subproject of another project. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently. See /subprojects for more information.
Subproject details¶
Subprojects listing¶
Subproject create¶
Subproject delete¶
Translations¶
Translations are the same version of a Project in a different language. See /localization for more information.
Translations listing¶
Redirects¶
Redirects allow the author to redirect an old URL of the documentation to a new one. This is useful when pages are moved around in the structure of the documentation set. See /user-defined-redirects for more information.
Redirect details¶
Redirects listing¶
Redirect create¶
Redirect update¶
Redirect delete¶
Environment variables¶
Environment variables are variables that you can define for your project. These variables are used in the build process when building your documentation. They are for example useful to define secrets in a safe way that can be used by your documentation to build properly. Environment variables can also be made public, allowing for them to be used in PR builds. See /environment-variables.
Environment variable details¶
Environment variables listing¶
Environment variable create¶
Environment variable delete¶
Organizations¶
注釈
The /api/v3/organizations/ endpoint is only available in Read the Docs for Business currently.
We plan to have organizations on |org_brand| in a near future and we will add support for this endpoint at the same time.
Organizations list¶
Organization details¶
Organization projects list¶
Embed¶
Additional APIs¶
- Server side search API.