The Read the Docs API uses 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 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.
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.
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.
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.
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.