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.
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).
Tip
You can browse the full API by accessing its root URL: https://readthedocs.org/api/v3/
Tip
You can browse the full API by accessing its root URL: https://readthedocs.com/api/v3/
Note
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.
Projects
Projects list
- GET /api/v3/projects/
Retrieve a list of all the projects for the current logged in user.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/
import requests URL = 'https://readthedocs.org/api/v3/projects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 25, "next": "/api/v3/projects/?limit=10&offset=10", "previous": null, "results": [{ "id": 12345, "name": "Pip", "slug": "pip", "created": "2010-10-23T18:12:31+00:00", "modified": "2018-12-11T07:21:11+00:00", "language": { "code": "en", "name": "English" }, "programming_language": { "code": "py", "name": "Python" }, "repository": { "url": "https://github.com/pypa/pip", "type": "git" }, "default_version": "stable", "default_branch": "master", "subproject_of": null, "translation_of": null, "urls": { "documentation": "http://pip.pypa.io/en/stable/", "home": "https://pip.pypa.io/" }, "tags": [ "distutils", "easy_install", "egg", "setuptools", "virtualenv" ], "users": [ { "username": "dstufft" } ], "active_versions": { "stable": "{VERSION}", "latest": "{VERSION}", "19.0.2": "{VERSION}" }, "_links": { "_self": "/api/v3/projects/pip/", "versions": "/api/v3/projects/pip/versions/", "builds": "/api/v3/projects/pip/builds/", "subprojects": "/api/v3/projects/pip/subprojects/", "superproject": "/api/v3/projects/pip/superproject/", "redirects": "/api/v3/projects/pip/redirects/", "translations": "/api/v3/projects/pip/translations/" } }] }
- Query Parameters:
name (string) – return projects with matching name
slug (string) – return projects with matching slug
language (string) – language code as
en
,es
,ru
, etc.programming_language (string) – programming language code as
py
,js
, etc.
The
results
in response is an array of project data, which is same asGET /api/v3/projects/(string:project_slug)/
.Note
Read the Docs for Business, also accepts
- Query Parameters:
expand (string) – Add additional fields in the response. Allowed values are:
organization
.
Project details
- GET /api/v3/projects/(string: project_slug)/
Retrieve details of a single project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "id": 12345, "name": "Pip", "slug": "pip", "created": "2010-10-23T18:12:31+00:00", "modified": "2018-12-11T07:21:11+00:00", "language": { "code": "en", "name": "English" }, "programming_language": { "code": "py", "name": "Python" }, "repository": { "url": "https://github.com/pypa/pip", "type": "git" }, "default_version": "stable", "default_branch": "master", "subproject_of": null, "translation_of": null, "urls": { "documentation": "http://pip.pypa.io/en/stable/", "home": "https://readthedocs.org/projects/pip/", "downloads": "https://readthedocs.org/projects/pip/downloads/", "builds": "https://readthedocs.org/projects/pip/builds/", "versions": "https://readthedocs.org/projects/pip/versions/", }, "tags": [ "distutils", "easy_install", "egg", "setuptools", "virtualenv" ], "users": [ { "username": "dstufft" } ], "active_versions": { "stable": "{VERSION}", "latest": "{VERSION}", "19.0.2": "{VERSION}" }, "privacy_level": "public", "external_builds_privacy_level": "public", "versioning_scheme": "multiple_versions_with_translations", "_links": { "_self": "/api/v3/projects/pip/", "versions": "/api/v3/projects/pip/versions/", "builds": "/api/v3/projects/pip/builds/", "subprojects": "/api/v3/projects/pip/subprojects/", "superproject": "/api/v3/projects/pip/superproject/", "redirects": "/api/v3/projects/pip/redirects/", "translations": "/api/v3/projects/pip/translations/" } }
- Query Parameters:
expand (string) – Add additional fields in the response. Allowed values are:
active_versions
. Multiple fields can be passed separated by commas.
Note
versioning_scheme
can be one of the following values:multiple_versions_with_translations
multiple_versions_without_translations
single_version_without_translations
Note
Read the Docs for Business, also accepts
- Query Parameters:
expand (string) – Add additional fields in the response. Allowed values are:
organization
.
Note
The
single_version
attribute is deprecated, useversioning_scheme
instead.
Project create
- POST /api/v3/projects/
Import a project under authenticated user.
Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.post( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "name": "Test Project", "repository": { "url": "https://github.com/readthedocs/template", "type": "git" }, "homepage": "http://template.readthedocs.io/", "programming_language": "py", "language": "es", "privacy_level": "public", "external_builds_privacy_level": "public", "tags": [ "automation", "sphinx" ] }
Example response:
Note
Read the Docs for Business, also accepts
- Request JSON Object:
organization (string) – required organization’s slug under the project will be imported.
teams (string) – optional teams’ slugs the project will belong to.
Note
Privacy levels are only available in Read the Docs for Business.
Project update
- PATCH /api/v3/projects/(string: project_slug)/
Update an existing project.
Example request:
$ curl \ -X PATCH \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.patch( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "name": "New name for the project", "repository": { "url": "https://github.com/readthedocs/readthedocs.org", "type": "git" }, "language": "ja", "programming_language": "py", "homepage": "https://readthedocs.org/", "tags" : [ "extension", "mkdocs" ] "default_version": "v0.27.0", "default_branch": "develop", "analytics_code": "UA000000", "analytics_disabled": false, "versioning_scheme": "multiple_versions_with_translations", "external_builds_enabled": true, "privacy_level": "public", "external_builds_privacy_level": "public" }
Note
Adding
tags
will replace existing tags with the new list, and if omitted won’t change the tags.Note
Privacy levels are only available in Read the Docs for Business.
- Status Codes:
204 No Content – Updated successfully
Project versions sync
- POST /api/v3/projects/(string: project_slug)/sync-versions/
Trigger a background task to sync the versions of the project.
Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" \ https://readthedocs.org/api/v3/projects/pip/sync-versions/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/sync-versions/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.post( URL, headers=HEADERS, ) print(response.json())
- Status Codes:
202 Accepted – Task created successfully
400 Bad Request – Bad request, task not created
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
- GET /api/v3/projects/(string: project_slug)/versions/
Retrieve a list of all versions for a project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/versions/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 25, "next": "/api/v3/projects/pip/versions/?limit=10&offset=10", "previous": null, "results": ["VERSION"] }
- Query Parameters:
active (boolean) – return only active versions
built (boolean) – return only built versions
privacy_level (string) – return versions with specific privacy level (
public
orprivate
)slug (string) – return versions with matching slug
type (string) – return versions with specific type (
branch
ortag
)verbose_name (string) – return versions with matching version name
Version detail
- GET /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/
Retrieve details of a single version.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/stable/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/versions/stable/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "id": 71652437, "slug": "stable", "verbose_name": "stable", "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914", "ref": "19.0.2", "built": true, "active": true, "aliases": ["VERSION"], "hidden": false, "type": "tag", "privacy_level": "public", "downloads": { "pdf": "https://pip.readthedocs.io/_/downloads/pdf/pip/stable/", "htmlzip": "https://pip.readthedocs.io/_/downloads/htmlzip/pip/stable/", "epub": "https://pip.readthedocs.io/_/downloads/epub/pip/stable/" }, "urls": { "dashboard": { "edit": "https://readthedocs.org/dashboard/pip/version/stable/edit/" }, "documentation": "https://pip.pypa.io/en/stable/", "vcs": "https://github.com/pypa/pip/tree/19.0.2" }, "_links": { "_self": "/api/v3/projects/pip/versions/stable/", "builds": "/api/v3/projects/pip/versions/stable/builds/", "project": "/api/v3/projects/pip/" } }
- Response JSON Object:
ref (string) – the version slug where the
stable
version points to.null
when it’s not the stable version.built (boolean) – the version has at least one successful build.
Version update
- PATCH /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/
Update a version.
When a version is deactivated, its documentation is removed, and when it’s activated, a new build is triggered.
Updates to a version also invalidates its CDN cache.
Example request:
$ curl \ -X PATCH \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/0.23/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/versions/0.23/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.patch( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "active": true, "hidden": false, "privacy_level": "public" }
- Status Codes:
204 No Content – Updated successfully
Note
Privacy levels are only available in Read the Docs for Business.
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 Build process overview for more information.
Build details
- GET /api/v3/projects/(str: project_slug)/builds/(int: build_id)/
Retrieve details of a single build for a project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "id": 8592686, "version": "latest", "project": "pip", "created": "2018-06-19T15:15:59+00:00", "finished": "2018-06-19T15:16:58+00:00", "duration": 59, "state": { "code": "finished", "name": "Finished" }, "success": true, "error": null, "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30", "config": { "version": "1", "formats": [ "htmlzip", "epub", "pdf" ], "python": { "version": 3, "install": [ { "requirements": ".../stable/tools/docs-requirements.txt" } ], }, "conda": null, "build": { "image": "readthedocs/build:latest" }, "doctype": "sphinx_htmldir", "sphinx": { "builder": "sphinx_htmldir", "configuration": ".../stable/docs/html/conf.py", "fail_on_warning": false }, "mkdocs": { "configuration": null, "fail_on_warning": false }, "submodules": { "include": "all", "exclude": [], "recursive": true } }, "_links": { "_self": "/api/v3/projects/pip/builds/8592686/", "project": "/api/v3/projects/pip/", "version": "/api/v3/projects/pip/versions/latest/" } }
- Response JSON Object:
created (string) – The ISO-8601 datetime when the build was created.
finished (string) – The ISO-8601 datetime when the build has finished.
duration (integer) – The length of the build in seconds.
state (string) – The state of the build (one of
triggered
,building
,installing
,cloning
,finished
orcancelled
)error (string) – An error message if the build was unsuccessful
- Query Parameters:
expand (string) – Add additional fields in the response. Allowed value is
config
.
Builds listing
- GET /api/v3/projects/(str: project_slug)/builds/
Retrieve list of all the builds on this project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/builds/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 15, "next": "/api/v3/projects/pip/builds?limit=10&offset=10", "previous": null, "results": ["BUILD"] }
- Query Parameters:
commit (string) – commit hash to filter the builds returned by commit
running (boolean) – filter the builds that are currently building/running
Build triggering
- POST /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/builds/
Trigger a new build for the
version_slug
version of this project.Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/latest/builds/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/versions/latest/builds/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.post(URL, headers=HEADERS) print(response.json())
Example response:
{ "build": "{BUILD}", "project": "{PROJECT}", "version": "{VERSION}" }
- Status Codes:
202 Accepted – the build was triggered
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
- GET /api/v3/projects/(str: project_slug)/subprojects/(str: alias_slug)/
Retrieve details of a subproject relationship.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "alias": "subproject-alias", "child": ["PROJECT"], "_links": { "parent": "/api/v3/projects/pip/" } }
Subprojects listing
- GET /api/v3/projects/(str: project_slug)/subprojects/
Retrieve a list of all sub-projects for a project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/subprojects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 25, "next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10", "previous": null, "results": ["SUBPROJECT RELATIONSHIP"] }
Subproject create
- POST /api/v3/projects/(str: project_slug)/subprojects/
Create a subproject relationship between two projects.
Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/subprojects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.post( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "child": "subproject-child-slug", "alias": "subproject-alias" }
Note
child
must be a project that you have access to. Or if you are using Business hosting, additionally the project must be under the same organization as the parent project.Example response:
- Response JSON Object:
child (string) – slug of the child project in the relationship.
alias (string) – optional slug alias to be used in the URL (e.g
/projects/<alias>/en/latest/
). If not provided, child project’s slug is used as alias.
- Status Codes:
201 Created – Subproject created successfully
Subproject delete
- DELETE /api/v3/projects/(str: project_slug)/subprojects/(str: alias_slug)/
Delete a subproject relationship.
Example request:
$ curl \ -X DELETE \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.delete(URL, headers=HEADERS) print(response.json())
- Status Codes:
204 No Content – Subproject deleted successfully
Translations
Translations are the same version of a Project in a different language. See Localization and Internationalization for more information.
Translations listing
- GET /api/v3/projects/(str: project_slug)/translations/
Retrieve a list of all translations for a project.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/translations/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/translations/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 25, "next": "/api/v3/projects/pip/translations/?limit=10&offset=10", "previous": null, "results": [{ "id": 12345, "name": "Pip", "slug": "pip", "created": "2010-10-23T18:12:31+00:00", "modified": "2018-12-11T07:21:11+00:00", "language": { "code": "en", "name": "English" }, "programming_language": { "code": "py", "name": "Python" }, "repository": { "url": "https://github.com/pypa/pip", "type": "git" }, "default_version": "stable", "default_branch": "master", "subproject_of": null, "translation_of": null, "urls": { "documentation": "http://pip.pypa.io/en/stable/", "home": "https://pip.pypa.io/" }, "tags": [ "distutils", "easy_install", "egg", "setuptools", "virtualenv" ], "users": [ { "username": "dstufft" } ], "active_versions": { "stable": "{VERSION}", "latest": "{VERSION}", "19.0.2": "{VERSION}" }, "_links": { "_self": "/api/v3/projects/pip/", "versions": "/api/v3/projects/pip/versions/", "builds": "/api/v3/projects/pip/builds/", "subprojects": "/api/v3/projects/pip/subprojects/", "superproject": "/api/v3/projects/pip/superproject/", "redirects": "/api/v3/projects/pip/redirects/", "translations": "/api/v3/projects/pip/translations/" } }] }
The
results
in response is an array of project data, which is same asGET /api/v3/projects/(string:project_slug)/
.
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 Redirects for more information.
Redirect details
- GET /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/
Retrieve details of a single redirect for a project.
Example request
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/redirects/1/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response
{ "pk": 1, "created": "2019-04-29T10:00:00Z", "modified": "2019-04-29T12:00:00Z", "project": "pip", "from_url": "/docs/", "to_url": "/documentation/", "type": "page", "http_status": 302, "description": "", "enabled": true, "force": false, "position": 0, "_links": { "_self": "/api/v3/projects/pip/redirects/1/", "project": "/api/v3/projects/pip/" } }
Redirects listing
- GET /api/v3/projects/(str: project_slug)/redirects/
Retrieve list of all the redirects for this project.
Example request
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/redirects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response
{ "count": 25, "next": "/api/v3/projects/pip/redirects/?limit=10&offset=10", "previous": null, "results": ["REDIRECT"] }
Redirect create
- POST /api/v3/projects/(str: project_slug)/redirects/
Create a redirect for this project.
Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/redirects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.post( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "from_url": "/docs/", "to_url": "/documentation/", "type": "page", "position": 0, }
Note
type
can be one ofpage
,exact
,clean_url_to_html
andhtml_to_clean_url
.Depending on the
type
of the redirect, some fields may not be needed:page
andexact
types requirefrom_url
andto_url
.clean_url_to_html
andhtml_to_clean_url
types do not requirefrom_url
andto_url
.
Position starts at 0 and is used to order redirects.
Example response:
- Status Codes:
201 Created – redirect created successfully
Redirect update
- PUT /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/
Update a redirect for this project.
Example request:
$ curl \ -X PUT \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/redirects/1/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.put( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "from_url": "/docs/", "to_url": "/documentation.html", "type": "page" }
Note
If the position of the redirect is changed, it will be inserted in the new position and the other redirects will be reordered.
Example response:
Redirect delete
- DELETE /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/
Delete a redirect for this project.
Example request:
$ curl \ -X DELETE \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/redirects/1/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.delete(URL, headers=HEADERS) print(response.json())
- Status Codes:
204 No Content – Redirect deleted successfully
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 variable overview.
Environment variable details
- GET /api/v3/projects/(str: project_slug)/environmentvariables/(int: environmentvariable_id)/
Retrieve details of a single environment variable for a project.
Example request
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response
{ "_links": { "_self": "https://readthedocs.org/api/v3/projects/project/environmentvariables/1/", "project": "https://readthedocs.org/api/v3/projects/project/" }, "created": "2019-04-29T10:00:00Z", "modified": "2019-04-29T12:00:00Z", "pk": 1, "project": "project", "public": false, "name": "ENVVAR" }
Environment variables listing
- GET /api/v3/projects/(str: project_slug)/environmentvariables/
Retrieve list of all the environment variables for this project.
Example request
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/environmentvariables/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response
{ "count": 15, "next": "/api/v3/projects/pip/environmentvariables/?limit=10&offset=10", "previous": null, "results": ["ENVIRONMENTVARIABLE"] }
Environment variable create
- POST /api/v3/projects/(str: project_slug)/environmentvariables/
Create an environment variable for this project.
Example request:
$ curl \ -X POST \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/ \ -H "Content-Type: application/json" \ -d @body.json
import requests import json URL = 'https://readthedocs.org/api/v3/projects/pip/environmentvariables/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} data = json.load(open('body.json', 'rb')) response = requests.post( URL, json=data, headers=HEADERS, ) print(response.json())
The content of
body.json
is like,{ "name": "MYVAR", "value": "My secret value" }
Example response:
See Environment Variable details
- Status Codes:
201 Created – Environment variable created successfully
Environment variable delete
- DELETE /api/v3/projects/(str: project_slug)/environmentvariables/(int: environmentvariable_id)/
Delete an environment variable for this project.
Example request:
$ curl \ -X DELETE \ -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/
import requests URL = 'https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.delete(URL, headers=HEADERS) print(response.json())
- Request Headers:
Authorization – token to authenticate.
- Status Codes:
204 No Content – Environment variable deleted successfully
Organizations
Note
The /api/v3/organizations/
endpoint is only available in Read the Docs for Business currently.
We plan to have organizations on Read the Docs Community in a near future and we will add support for this endpoint at the same time.
Organizations list
- GET /api/v3/organizations/
Retrieve a list of all the organizations for the current logged in user.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/
import requests URL = 'https://readthedocs.com/api/v3/organizations/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 1, "next": null, "previous": null, "results": [ { "_links": { "_self": "https://readthedocs.com/api/v3/organizations/pypa/", "projects": "https://readthedocs.com/api/v3/organizations/pypa/projects/" }, "created": "2019-02-22T21:54:52.768630Z", "description": "", "disabled": false, "email": "pypa@psf.org", "modified": "2020-07-02T12:35:32.418423Z", "name": "Python Package Authority", "owners": [ { "username": "dstufft" } ], "slug": "pypa", "url": "https://github.com/pypa/" } }
Organization details
- GET /api/v3/organizations/(string: organization_slug)/
Retrieve details of a single organization.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/pypa/
import requests URL = 'https://readthedocs.com/api/v3/organizations/pypa/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "_links": { "_self": "https://readthedocs.com/api/v3/organizations/pypa/", "projects": "https://readthedocs.com/api/v3/organizations/pypa/projects/" }, "created": "2019-02-22T21:54:52.768630Z", "description": "", "disabled": false, "email": "pypa@psf.com", "modified": "2020-07-02T12:35:32.418423Z", "name": "Python Package Authority", "owners": [ { "username": "dstufft" } ], "slug": "pypa", "url": "https://github.com/pypa/" }
Organization projects list
- GET /api/v3/organizations/(string: organization_slug)/projects/
Retrieve list of projects under an organization.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/pypa/projects/
import requests URL = 'https://readthedocs.com/api/v3/organizations/pypa/projects/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 1, "next": null, "previous": null, "results": [ { "_links": { "_self": "https://readthedocs.com/api/v3/projects/pypa-pip/", "builds": "https://readthedocs.com/api/v3/projects/pypa-pip/builds/", "environmentvariables": "https://readthedocs.com/api/v3/projects/pypa-pip/environmentvariables/", "redirects": "https://readthedocs.com/api/v3/projects/pypa-pip/redirects/", "subprojects": "https://readthedocs.com/api/v3/projects/pypa-pip/subprojects/", "superproject": "https://readthedocs.com/api/v3/projects/pypa-pip/superproject/", "translations": "https://readthedocs.com/api/v3/projects/pypa-pip/translations/", "versions": "https://readthedocs.com/api/v3/projects/pypa-pip/versions/" }, "created": "2019-02-22T21:59:13.333614Z", "default_branch": "master", "default_version": "latest", "homepage": null, "id": 2797, "language": { "code": "en", "name": "English" }, "modified": "2019-08-08T16:27:25.939531Z", "name": "pip", "programming_language": { "code": "py", "name": "Python" }, "repository": { "type": "git", "url": "https://github.com/pypa/pip" }, "slug": "pypa-pip", "subproject_of": null, "tags": [], "translation_of": null, "urls": { "builds": "https://readthedocs.com/projects/pypa-pip/builds/", "documentation": "https://pypa-pip.readthedocs-hosted.com/en/latest/", "home": "https://readthedocs.com/projects/pypa-pip/", "versions": "https://readthedocs.com/projects/pypa-pip/versions/" } } ] }
Organization teams list
- GET /api/v3/organizations/(string: organization_slug)/teams/
Retrieve list of teams under an organization.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/pypa/teams/
import requests URL = 'https://readthedocs.com/api/v3/organizations/pypa/teams/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 2, "next": null, "previous": null, "results": [ { "access": "admin", "created": "2024-07-01T21:19:55.573819Z", "modified": "2024-07-01T21:19:55.573837Z", "name": "Admins", "slug": "admins" }, { "access": "readonly", "created": "2024-07-01T21:19:55.593815Z", "modified": "2024-07-01T21:19:55.593829Z", "name": "Read Only", "slug": "read-only" } ] }
- Query Parameters:
expand (string) – Add additional fields in the response. Allowed values are:
members
.
Remote organizations
Remote organizations are the VCS organizations connected via
GitHub
, GitLab
and Bitbucket
.
Remote organization listing
- GET /api/v3/remote/organizations/
Retrieve a list of all Remote Organizations for the authenticated user.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/remote/organizations/
import requests URL = 'https://readthedocs.org/api/v3/remote/organizations/' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 20, "next": "api/v3/remote/organizations/?limit=10&offset=10", "previous": null, "results": [ { "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4", "created": "2019-04-29T10:00:00Z", "modified": "2019-04-29T12:00:00Z", "name": "Organization Name", "pk": 1, "slug": "organization", "url": "https://github.com/organization", "vcs_provider": "github" } ] }
The
results
in response is an array of remote organizations data.- Query Parameters:
name (string) – return remote organizations with containing the name
vcs_provider (string) – return remote organizations for specific vcs provider (
github
,gitlab
orbitbucket
)
- Request Headers:
Authorization – token to authenticate.
Remote repositories
Remote repositories are the importable repositories connected via
GitHub
, GitLab
and Bitbucket
.
Remote repository listing
- GET /api/v3/remote/repositories/
Retrieve a list of all Remote Repositories for the authenticated user.
Example request:
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/remote/repositories/?expand=remote_organization
import requests URL = 'https://readthedocs.org/api/v3/remote/repositories/?expand=remote_organization' TOKEN = '<token>' HEADERS = {'Authorization': f'token {TOKEN}'} response = requests.get(URL, headers=HEADERS) print(response.json())
Example response:
{ "count": 20, "next": "api/v3/remote/repositories/?expand=remote_organization&limit=10&offset=10", "previous": null, "results": [ { "remote_organization": { "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4", "created": "2019-04-29T10:00:00Z", "modified": "2019-04-29T12:00:00Z", "name": "Organization Name", "pk": 1, "slug": "organization", "url": "https://github.com/organization", "vcs_provider": "github" }, "projects": [{ "id": 12345, "name": "project", "slug": "project", "created": "2010-10-23T18:12:31+00:00", "modified": "2018-12-11T07:21:11+00:00", "language": { "code": "en", "name": "English" }, "programming_language": { "code": "py", "name": "Python" }, "repository": { "url": "https://github.com/organization/project", "type": "git" }, "default_version": "stable", "default_branch": "master", "subproject_of": null, "translation_of": null, "urls": { "documentation": "http://project.readthedocs.io/en/stable/", "home": "https://readthedocs.org/projects/project/" }, "tags": [ "test" ], "users": [ { "username": "dstufft" } ], "_links": { "_self": "/api/v3/projects/project/", "versions": "/api/v3/projects/project/versions/", "builds": "/api/v3/projects/project/builds/", "subprojects": "/api/v3/projects/project/subprojects/", "superproject": "/api/v3/projects/project/superproject/", "redirects": "/api/v3/projects/project/redirects/", "translations": "/api/v3/projects/project/translations/" } }], "avatar_url": "https://avatars3.githubusercontent.com/u/test-organization?v=4", "clone_url": "https://github.com/organization/project.git", "created": "2019-04-29T10:00:00Z", "description": "This is a test project.", "full_name": "organization/project", "html_url": "https://github.com/organization/project", "modified": "2019-04-29T12:00:00Z", "name": "project", "pk": 1, "ssh_url": "git@github.com:organization/project.git", "vcs": "git", "vcs_provider": "github", "default_branch": "master", "private": false, "admin": true } ] }
The
results
in response is an array of remote repositories data.- Query Parameters:
name (string) – return remote repositories containing the name
full_name (string) – return remote repositories containing the full name (it includes the username/organization the project belongs to)
vcs_provider (string) – return remote repositories for specific vcs provider (
github
,gitlab
orbitbucket
)organization (string) – return remote repositories for specific remote organization (using remote organization
slug
)expand (string) – Add additional fields in the response. Allowed values are:
remote_organization
. Multiple fields can be passed separated by commas.
- Request Headers:
Authorization – token to authenticate.
Embed
- GET /api/v3/embed/
Retrieve HTML-formatted content from documentation page or section. Read How to embed content from your documentation to know more about how to use this endpoint.
Warning
The content will be returned as is, without any sanitization or escaping. You should not include content from arbitrary projects, or projects you do not trust.
Example request:
curl https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23read-the-docs-features
Example response:
{ "url": "https://docs.readthedocs.io/en/latest/features.html#read-the-docs-features", "fragment": "read-the-docs-features", "content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...", "external": false }
- Response JSON Object:
url (string) – URL of the document.
fragment (string) – fragmet part of the URL used to query the page.
content (string) – HTML content of the section.
external (string) – whether or not the page is hosted on Read the Docs or externally.
- Query Parameters:
url (string) – full URL of the document (with optional fragment) to fetch content from.
doctool (string) – optional documentation tool key name used to generate the target documentation (currently, only
sphinx
is accepted)doctoolversion (string) – optional documentation tool version used to generate the target documentation (e.g.
4.2.0
).
Note
Passing
?doctool=
and?doctoolversion=
may improve the response, since the endpoint will know more about the exact structure of the HTML and can make better decisions.