API v3¶

The Read the Docs API uses REST. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure.

Table of contents

Authentication and authorization¶

Requests to the Read the Docs public API are for public and private information. All endpoints require authentication.

Token¶

The Authorization HTTP header can be specified with Token <your-access-token> to authenticate as a user and have the same permissions that the user itself.

注釈

You will find your access Token under your profile settings.

Session¶

警告

Authentication via session is not enabled yet.

Session authentication is allowed on very specific endpoints, to allow hitting the API when reading documentation.

When a user is trying to authenticate via session, CSRF check is performed.

Resources¶

This section shows all the resources that are currently available in APIv3. There are some URL attributes that applies to all of these resources:

?fields=:	Specify which fields are going to be returned in the response.
?omit=:	Specify which fields are going to be omitted from the response.
?expand=:	Some resources allow to expand/add extra fields on their responses (see Project details for example).

ちなみに

You can browse the full API by accessing its root URL: https://readthedocs.org/api/v3/

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"]
}

Query Parameters:
	language (string) -- language code as `en`, `es`, `ru`, etc. programming_language (string) -- programming language code as `py`, `js`, etc.

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

Query Parameters:
	expand (string) -- 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.

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

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

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

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/",
    "default_version": "v0.27.0",
    "default_branch": "develop",
    "analytics_code": "UA000000",
    "single_version": false,

}

Status Codes:	204 No Content -- Updated successfully

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"]
}

Query Parameters:
	active (boolean) -- return only active versions built (boolean) -- return only built versions

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,
    "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:
	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.
Query Parameters:
	expand (string) -- 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.

Version update¶

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

Update a version.

Example request:

$ curl \
  -X PATCH \
  -H "Authorization: Token <token>" https://readthedocs.org/api/v3/projects/pip/version/0.23/ \
  -H "Content-Type: application/json" \
  -d @body.json

The content of body.json is like,

{
    "active": true,
}

Status Codes:	204 No Content -- Updated successfully

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 ビルド処理 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:
	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`, or `finished`) error (string) -- An error message if the build was unsuccessful
Query Parameters:
	expand (string) -- allows to add/expand some extra 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/

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/

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 サブプロジェクト 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/

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/

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

The content of body.json is like,

{
    "child": "subproject-child-slug",
    "alias": "subproject-alias"
}

Example response:

See Subproject details

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 sucessfully

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/

Status Codes:	204 No Content -- Subproject deleted successfully

Translations¶

Translations are the same version of a Project in a different language. See ドキュメントの多言語化 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"]
}

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

注釈

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

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

The content of body.json is like,

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

Example response:

See Redirect details

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/

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

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/

Request Headers:
	Authorization -- token to authenticate.
Status Codes:	204 No Content -- Environment variable deleted successfully