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.
Table of contents
Requests to the Read the Docs public API are for public and private information. All endpoints require authentication.
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.
.. tabs::
.. tab:: |org_brand|
.. note::
On |org_brand|, you will find your access Token under
`your profile settings <https://readthedocs.org/accounts/tokens/>`__.
.. tab:: |com_brand|
.. note::
On |com_brand|, you will find your access Token under
`your profile settings <https://readthedocs.com/accounts/tokens/>`__.
Warning
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, :abbr:`CSRF (Cross-site request forgery)` check is performed.
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). |
.. tabs::
.. tab:: |org_brand|
.. tip::
You can browse the full API by accessing its root URL: https://readthedocs.org/api/v3/
.. tab:: |com_brand|
.. tip::
You can browse the full API by accessing its root URL: https://readthedocs.com/api/v3/
Note
If you are using :doc:`Read the Docs for Business </commercial/index>` 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.
.. http:get:: /api/v3/projects/
Retrieve a list of all the projects for the current logged in user.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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}"
},
"analytics": {
"google": {
"code": "UA-XXXXX"
},
"readthedocs": {
"enabled": true
}
}
"_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 string name: return projects with matching name
:query string slug: return projects with matching slug
:query string language: language code as ``en``, ``es``, ``ru``, etc.
:query string programming_language: programming language code as ``py``, ``js``, etc.
The ``results`` in response is an array of project data,
which is same as :http:get:`/api/v3/projects/(string:project_slug)/`.
.. note::
.. FIXME: we can't use :query string: here because it doesn't render properly
:doc:`Read the Docs for Business </commercial/index>`, also accepts
:Query Parameters:
* **expand** (*string*) -- with ``organization`` and ``teams``.
.. http:get:: /api/v3/projects/(string:project_slug)/
Retrieve details of a single project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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}"
},
"privacy_level": "public",
"external_builds_privacy_level": "public",
"analytics": {
"google": {
"code": "UA-XXXXX"
},
"readthedocs": {
"enabled": true
}
}
"_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 string expand: allows to add/expand some extra fields in the response.
Allowed values are ``active_versions``, ``active_versions.last_build`` and
``active_versions.last_build.config``. Multiple fields can be passed separated by commas.
.. note::
.. FIXME: we can't use :query string: here because it doesn't render properly
:doc:`Read the Docs for Business </commercial/index>`, also accepts
:Query Parameters:
* **expand** (*string*) -- with ``organization`` and ``teams``.
.. http:post:: /api/v3/projects/
Import a project under authenticated user.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X POST \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"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**:
`See Project details <#project-details>`__
.. note::
.. FIXME: we can't use :query string: here because it doesn't render properly
:doc:`Read the Docs for Business </commercial/index>`, 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 :doc:`Read the Docs for Business </commercial/index>`.
.. http:patch:: /api/v3/projects/(string:project_slug)/
Update an existing project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X PATCH \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"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,
"single_version": false,
"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 :doc:`Read the Docs for Business </commercial/index>`.
:statuscode 204: Updated successfully
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 :doc:`/versions` for more information.
.. http:get:: /api/v3/projects/(string:project_slug)/versions/
Retrieve a list of all versions for a project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"count": 25,
"next": "/api/v3/projects/pip/versions/?limit=10&offset=10",
"previous": null,
"results": ["VERSION"]
}
:query boolean active: return only active versions
:query boolean built: return only built versions
:query string privacy_level: return versions with specific privacy level (``public`` or ``private``)
:query string slug: return versions with matching slug
:query string type: return versions with specific type (``branch`` or ``tag``)
:query string verbose_name: return versions with matching version name
.. http:get:: /api/v3/projects/(string:project_slug)/versions/(string:version_slug)/
Retrieve details of a single version.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/stable/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"id": 71652437,
"slug": "stable",
"verbose_name": "stable",
"identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
"ref": "19.0.2",
"built": true,
"active": true,
"hidden": false,
"type": "tag",
"last_build": "{BUILD}",
"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/"
}
}
:>json string ref: the version slug where the ``stable`` version points to.
``null`` when it's not the stable version.
:>json boolean built: the version has at least one successful build.
:query string expand: allows to add/expand some extra fields in the response.
Allowed values are ``last_build`` and ``last_build.config``.
Multiple fields can be passed separated by commas.
.. http:patch:: /api/v3/projects/(string:project_slug)/versions/(string:version_slug)/
Update a version.
**Example request**:
.. tabs::
.. code-tab:: bash
$ 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
.. code-tab:: python
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,
.. sourcecode:: json
{
"active": true,
"hidden": false,
"privacy_level": "public"
}
:statuscode 204: Updated successfully
.. note::
Privacy levels are only available in :doc:`Read the Docs for Business </commercial/index>`.
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 :doc:`/builds` for more information.
.. http:get:: /api/v3/projects/(str:project_slug)/builds/(int:build_id)/
Retrieve details of a single build for a project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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"
}
],
"use_system_site_packages": false
},
"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/"
}
}
:>json string created: The ISO-8601 datetime when the build was created.
:>json string finished: The ISO-8601 datetime when the build has finished.
:>json integer duration: The length of the build in seconds.
:>json string state: The state of the build (one of ``triggered``, ``building``, ``installing``, ``cloning``, ``finished`` or ``cancelled``)
:>json string error: An error message if the build was unsuccessful
:query string expand: allows to add/expand some extra fields in the response.
Allowed value is ``config``.
.. http:get:: /api/v3/projects/(str:project_slug)/builds/
Retrieve list of all the builds on this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/builds/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"count": 15,
"next": "/api/v3/projects/pip/builds?limit=10&offset=10",
"previous": null,
"results": ["BUILD"]
}
:query string commit: commit hash to filter the builds returned by commit
:query boolean running: filter the builds that are currently building/running
.. http: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**:
.. tabs::
.. code-tab:: bash
$ curl \
-X POST \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/versions/latest/builds/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"build": "{BUILD}",
"project": "{PROJECT}",
"version": "{VERSION}"
}
:statuscode 202: the build was triggered
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 :doc:`/subprojects` for more information.
.. http:get:: /api/v3/projects/(str:project_slug)/subprojects/(str:alias_slug)/
Retrieve details of a subproject relationship.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"alias": "subproject-alias",
"child": ["PROJECT"],
"_links": {
"parent": "/api/v3/projects/pip/"
}
}
.. http:get:: /api/v3/projects/(str:project_slug)/subprojects/
Retrieve a list of all sub-projects for a project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"count": 25,
"next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10",
"previous": null,
"results": ["SUBPROJECT RELATIONSHIP"]
}
.. http:post:: /api/v3/projects/(str:project_slug)/subprojects/
Create a subproject relationship between two projects.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X POST \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"child": "subproject-child-slug",
"alias": "subproject-alias"
}
.. note::
``child`` must be a project that you have access to.
Or if you are using :doc:`/commercial/index`,
additionally the project must be under the same organization as the parent project.
**Example response**:
`See Subproject details <#subproject-details>`_
:>json string child: slug of the child project in the relationship.
:>json string alias: 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.
:statuscode 201: Subproject created successfully
.. http:delete:: /api/v3/projects/(str:project_slug)/subprojects/(str:alias_slug)/
Delete a subproject relationship.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X DELETE \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/
.. code-tab:: python
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())
:statuscode 204: Subproject deleted successfully
Translations are the same version of a Project in a different language. See :doc:`/localization` for more information.
.. http:get:: /api/v3/projects/(str:project_slug)/translations/
Retrieve a list of all translations for a project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/translations/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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 as :http:get:`/api/v3/projects/(string:project_slug)/`.
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 :doc:`/user-defined-redirects` for more information.
.. http:get:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/
Retrieve details of a single redirect for a project.
**Example request**
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/
.. code-tab:: python
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**
.. sourcecode:: json
{
"pk": 1,
"created": "2019-04-29T10:00:00Z",
"modified": "2019-04-29T12:00:00Z",
"project": "pip",
"from_url": "/docs/",
"to_url": "/documentation/",
"type": "page",
"_links": {
"_self": "/api/v3/projects/pip/redirects/1/",
"project": "/api/v3/projects/pip/"
}
}
.. http:get:: /api/v3/projects/(str:project_slug)/redirects/
Retrieve list of all the redirects for this project.
**Example request**
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/
.. code-tab:: python
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**
.. sourcecode:: json
{
"count": 25,
"next": "/api/v3/projects/pip/redirects/?limit=10&offset=10",
"previous": null,
"results": ["REDIRECT"]
}
.. http:post:: /api/v3/projects/(str:project_slug)/redirects/
Create a redirect for this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X POST \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"from_url": "/docs/",
"to_url": "/documentation/",
"type": "page"
}
.. note::
``type`` can be one of ``prefix``, ``page``, ``exact``, ``sphinx_html`` and ``sphinx_htmldir``.
Depending on the ``type`` of the redirect, some fields may not be needed:
* ``prefix`` type does not require ``to_url``.
* ``page`` and ``exact`` types require ``from_url`` and ``to_url``.
* ``sphinx_html`` and ``sphinx_htmldir`` types do not require ``from_url`` and ``to_url``.
**Example response**:
`See Redirect details <#redirect-details>`_
:statuscode 201: redirect created successfully
.. http:put:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/
Update a redirect for this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X PUT \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"from_url": "/docs/",
"to_url": "/documentation.html",
"type": "page"
}
**Example response**:
`See Redirect details <#redirect-details>`_
.. http:delete:: /api/v3/projects/(str:project_slug)/redirects/(int:redirect_id)/
Delete a redirect for this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X DELETE \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/redirects/1/
.. code-tab:: python
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())
:statuscode 204: Redirect deleted successfully
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 :doc:`/environment-variables`.
.. http:get:: /api/v3/projects/(str:project_slug)/environmentvariables/(int:environmentvariable_id)/
Retrieve details of a single environment variable for a project.
**Example request**
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/
.. code-tab:: python
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**
.. sourcecode:: json
{
"_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"
}
.. http:get:: /api/v3/projects/(str:project_slug)/environmentvariables/
Retrieve list of all the environment variables for this project.
**Example request**
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/
.. code-tab:: python
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**
.. sourcecode:: json
{
"count": 15,
"next": "/api/v3/projects/pip/environmentvariables/?limit=10&offset=10",
"previous": null,
"results": ["ENVIRONMENTVARIABLE"]
}
.. http:post:: /api/v3/projects/(str:project_slug)/environmentvariables/
Create an environment variable for this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X POST \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/ \
-H "Content-Type: application/json" \
-d @body.json
.. code-tab:: python
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,
.. sourcecode:: json
{
"name": "MYVAR",
"value": "My secret value"
}
**Example response**:
`See Environment Variable details <#environmentvariable-details>`_
:statuscode 201: Environment variable created successfully
.. http:delete:: /api/v3/projects/(str:project_slug)/environmentvariables/(int:environmentvariable_id)/
Delete an environment variable for this project.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl \
-X DELETE \
-H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/environmentvariables/1/
.. code-tab:: python
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())
:requestheader Authorization: token to authenticate.
:statuscode 204: Environment variable deleted successfully
Note
The /api/v3/organizations/ endpoint is only available in :doc:`Read the Docs for Business </commercial/index>` 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.
.. http:get:: /api/v3/organizations/
Retrieve a list of all the organizations for the current logged in user.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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": "[email protected]",
"modified": "2020-07-02T12:35:32.418423Z",
"name": "Python Package Authority",
"owners": [
{
"username": "dstufft"
}
],
"slug": "pypa",
"url": "https://github.com/pypa/"
}
}
.. http:get:: /api/v3/organizations/(string:organization_slug)/
Retrieve details of a single organization.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/pypa/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"_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": "[email protected]",
"modified": "2020-07-02T12:35:32.418423Z",
"name": "Python Package Authority",
"owners": [
{
"username": "dstufft"
}
],
"slug": "pypa",
"url": "https://github.com/pypa/"
}
.. http:get:: /api/v3/organizations/(string:organization_slug)/projects/
Retrieve list of projects under an organization.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.com/api/v3/organizations/pypa/projects/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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/"
}
}
]
}
Remote organizations are the VCS organizations connected via
GitHub, GitLab and Bitbucket.
.. http:get:: /api/v3/remote/organizations/
Retrieve a list of all Remote Organizations for the authenticated user.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/remote/organizations/
.. code-tab:: python
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**:
.. sourcecode:: json
{
"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 string name: return remote organizations with containing the name
:query string vcs_provider: return remote organizations for specific vcs provider (``github``, ``gitlab`` or ``bitbucket``)
:requestheader Authorization: token to authenticate.
Remote repositories are the importable repositories connected via
GitHub, GitLab and Bitbucket.
.. http:get:: /api/v3/remote/repositories/
Retrieve a list of all Remote Repositories for the authenticated user.
**Example request**:
.. tabs::
.. code-tab:: bash
$ curl -H "Authorization: Token <token>" https://readthedocs.org/api/v3/remote/repositories/?expand=projects,remote_organization
.. code-tab:: python
import requests
URL = 'https://readthedocs.org/api/v3/remote/repositories/?expand=projects,remote_organization'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())
**Example response**:
.. sourcecode:: json
{
"count": 20,
"next": "api/v3/remote/repositories/?expand=projects,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"
},
"project": [{
"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": "[email protected]: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 string name: return remote repositories containing the name
:query string vcs_provider: return remote repositories for specific vcs provider (``github``, ``gitlab`` or ``bitbucket``)
:query string organization: return remote repositories for specific remote organization (using remote organization ``slug``)
:query string expand: allows to add/expand some extra fields in the response.
Allowed values are ``projects`` and ``remote_organization``.
Multiple fields can be passed separated by commas.
:requestheader Authorization: token to authenticate.
.. http:get:: /api/v3/embed/
Retrieve HTML-formatted content from documentation page or section.
Read :doc:`/guides/embedding-content` to know more about how to use this endpoint.
**Example request**:
.. prompt:: bash $
curl https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23read-the-docs-features
**Example response**:
.. sourcecode:: js
{
"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
}
:>json string url: URL of the document.
:>json string fragment: fragmet part of the URL used to query the page.
:>json string content: HTML content of the section.
:>json string external: whether or not the page is hosted on Read the Docs or externally.
:query string url: full URL of the document (with optional fragment) to fetch content from.
:query string doctool: *optional* documentation tool key name used to generate the target documentation (currently, only ``sphinx`` is accepted)
:query string doctoolversion: *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.