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.

Warning

APIv3 is currently under development and it’s not ready to use yet.

Note

If you want to beta test it, please get in touch with us so we can give you early access.

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

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, CSRF check is performed.

Resources

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/

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/?limit=10&offset=10",
    "previous": null,
    "results": ["PROJECT"]
}
Response JSON Object:
 
  • count (integer) – total number of projects.
  • next (string) – URI for next set of projects.
  • previous (string) – URI for previous set of projects.
  • results (array) – array of project objects.
Query Parameters:
 
  • name (string) – name of the project.
  • name__contains (string) – part of the name of the project.
  • slug (string) – slug of the project.
  • slug__contains (string) – part of the slug of the project.
  • language (string) – language code as en, es, ru, etc.
  • privacy_level (string) – one of public, private, protected.
  • programming_language (string) – programming language code as py, js, etc.
  • repository_type (string) – one of git, hg, bzr, svn.
Request Headers:
 

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/

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",
    "privacy_level": {
        "code": "public",
        "name": "Public",
    },
    "subproject_of": null,
    "translation_of": null,
    "urls": {
        "documentation": "http://pip.pypa.io/en/stable/",
        "home": "https://pip.pypa.io/"
    },
    "tags": [
        "disutils",
        "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/"
    }
}
Response JSON Object:
 
  • name (string) – The name of the project.
  • slug (string) – The project slug (used in the URL).
Request Headers:
 
Status Codes:

Project create

POST /api/v3/projects/

Import a project into Read the Docs.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/ \
  -H "Content-Type: application/json" \
  -d @body.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"
}

Example response:

See Project details

Request Headers:
 
Status Codes:

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/

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/versions/?limit=10&offset=10",
    "previous": null,
    "results": ["VERSION"]
}
Response JSON Object:
 
  • count (integer) – Total number of Projects.
  • next (string) – URI for next set of Projects.
  • previous (string) – URI for previous set of Projects.
  • results (array) – Array of Version objects.
Query Parameters:
 
  • limit (integer) – limit number of object returned
  • offset (integer) – offset from the whole list returned
  • active (boolean) – whether return active versions only
  • built (boolean) – whether return only built version
Request Headers:
 

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/

Example response:

{
    "id": 71652437,
    "slug": "stable",
    "verbose_name": "stable",
    "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
    "ref": "19.0.2",
    "built": true,
    "active": true,
    "uploaded": true,
    "type": "tag",
    "last_build": "{BUILD}",
    "downloads": {
        "pdf": "https://readthedocs.org/projects/pip/downloads/pdf/stable/",
        "htmlzip": "https://readthedocs.org/projects/pip/downloads/htmlzip/stable/",
        "epub": "https://readthedocs.org/projects/pip/downloads/epub/stable/"
    },
    "urls": {
        "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:
 
  • id (integer) – ID for this version on the database
  • slug (string) – The slug for this version
  • verbose_name (string) – The name of the version
  • identifier (string) – A version control identifier for this version (eg. the commit hash of the tag)
  • ref (string) – tag or branch pointed by this version (available only when version is stable or latest)
  • built (string) – Whether this version has been built
  • active (string) – Whether this version is active
  • type (string) – The type of this version (typically “tag” or “branch”)
  • last_build (string) – Build object representing the last build of this version
  • downloads (array) – URLs to downloads of this version’s documentation
Request Headers:
 
Status Codes:

Version update

PATCH /api/v3/projects/(string: project_slug)/version/(string: version_slug)/

Edit a version.

Example request:

{
    "active": true,
    "privacy_level": "public"
}
Request Headers:
 
Status Codes:

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 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

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"
                }
            ],
            "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/"
    }
}
Response JSON Object:
 
  • id (integer) – The ID of the build
  • date (string) – The ISO-8601 datetime of the build.
  • duration (integer) – The length of the build in seconds.
  • 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)
  • builder (string) – The hostname server that built the docs
  • cold_storage (string) – Whether the build was removed from database and stored externally
Query Parameters:
 
  • include_config (boolean) – whether or not include the configs used for this build. Default is false
Request Headers:
 
Status Codes:

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/

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) – whether or not to filter the builds returned by currently building
Request Headers:
 

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/

Example response:

See Build details

Request Headers:
 
Status Codes:

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.

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/

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10",
    "previous": null,
    "results": ["PROJECT"]
}
Response JSON Object:
 
  • count (integer) – total number of projects.
  • next (string) – URI for next set of projects.
  • previous (string) – URI for previous set of projects.
  • results (array) – array of project objects.
Request Headers:
 

Translations

Translations are the same version of a Project in a different language. See Localization of Documentation 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/

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/translations/?limit=10&offset=10",
    "previous": null,
    "results": ["PROJECT"]
}
Response JSON Object:
 
  • count (integer) – total number of projects.
  • next (string) – URI for next set of projects.
  • previous (string) – URI for previous set of projects.
  • results (array) – array of project objects.
Request Headers:
 

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

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/

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",
    "_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/

Example response

{
    "count": 25,
    "next": "/api/v3/projects/pip/redirects/?limit=10&offset=10",
    "previous": null,
    "results": ["REDIRECT"]
}

Redirect create

POST /api/v3/projects/pip/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

The content of body.json is like,

{
    "from_url": "/docs/",
    "to_url": "/documentation/",
    "type": "page"
}

Example response:

See Redirect details

Request Headers:
 
Status Codes:

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

The content of body.json is like,

{
    "from_url": "/docs/",
    "to_url": "/documentation.html",
    "type": "page"
}

Example response:

See Redirect details

Request Headers:
 
Status Codes:

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/
Request Headers:
 
Status Codes:

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 useful to define secrets in a safe way that can be used by your documentation to build properly. See I Need Secrets (or Environment Variables) in my Build

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/

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",
"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/

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/pip/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

The content of body.json is like,

{
    "name": "MYVAR",
    "value": "My secret value"
}

Example response:

See Environment Variable details

Request Headers:
 
Status Codes:

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/
Request Headers:
 
Status Codes: