Read the Docs Public API

We have a limited public API that is available for you to get data out of the site. This document covers only part of the API provided. We have plans to create a read/write API, so that you can easily automate interactions with your project.

A basic API client using slumber

You can use Slumber to build basic API wrappers in python. Here is a simple example of using slumber to interact with the RTD API:

from __future__ import print_function
import slumber
import json

show_objs = True
api = slumber.API(base_url='http://readthedocs.org/api/v1/')

val = api.project.get(slug='pip')

if show_objs:
    for obj in val['objects']:
        print(json.dumps(obj, indent=4))
else:
    print(json.dumps(val, indent=4))

Alternatively you can try with the following value:

# fetch project pip without metadata.
val = api.project('pip').get()

# get a specific build
val = api.build(2592228).get()

# get the build of a specific project.
val = api.build.get(project__slug='read-the-docs')

# get a specific user by `username`
val = api.user.get(username='eric')

#val = api.version('pip').get()
#val = api.version('pip').get(slug='1.0.1')

#val = api.version('pip').highest.get()
#val = api.version('pip').highest('0.8').get()

API Endpoints

Feel free to use cURL and python to look at formatted json examples. You can also look at them in your browser, if it handles returned json.

curl http://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool

Root

GET /api/v1/
Retrieve a list of resources.
{
    "build": {
        "list_endpoint": "/api/v1/build/",
        "schema": "/api/v1/build/schema/"
    },
    "file": {
        "list_endpoint": "/api/v1/file/",
        "schema": "/api/v1/file/schema/"
    },
    "project": {
        "list_endpoint": "/api/v1/project/",
        "schema": "/api/v1/project/schema/"
    },
    "user": {
        "list_endpoint": "/api/v1/user/",
        "schema": "/api/v1/user/schema/"
    },
    "version": {
        "list_endpoint": "/api/v1/version/",
        "schema": "/api/v1/version/schema/"
    }
}
Response JSON Object:
 
  • list_endpoint (string) – API endpoint for resource.
  • schema (string) – API endpoint for schema of resource.

Builds

GET /api/v1/build/
Retrieve a list of Builds.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/build/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 86684
    },
    "objects": [BUILDS]
}
Response JSON Object:
 
  • limit (integer) – Number of Builds returned.
  • next (string) – URI for next set of Builds.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Builds.
  • total_count (integer) – Total number of Builds.
  • objects (array) – Array of Build objects.

Build

GET /api/v1/build/{id}/
Parameters:
  • id

    A Build id.

    Retrieve a single Build.

{
    "date": "2012-03-12T19:58:29.307403",
    "error": "SPHINX ERROR",
    "id": "91207",
    "output": "SPHINX OUTPUT",
    "project": "/api/v1/project/2599/",
    "resource_uri": "/api/v1/build/91207/",
    "setup": "HEAD is now at cd00d00 Merge pull request #181 from Nagyman/solr_setup\n",
    "setup_error": "",
    "state": "finished",
    "success": true,
    "type": "html",
    "version": "/api/v1/version/37405/"
}
Response JSON Object:
 
  • date (string) – Date of Build.
  • error (string) – Error from Sphinx build process.
  • id (string) – Build id.
  • output (string) – Output from Sphinx build process.
  • project (string) – URI for Project of Build.
  • resource_uri (string) – URI for Build.
  • setup (string) – Setup output from Sphinx build process.
  • setup_error (string) – Setup error from Sphinx build process.
  • state (string) – “triggered”, “building”, or “finished”
  • success (boolean) – Was build successful?
  • type (string) – Build type (“html”, “pdf”, “man”, or “epub”)
  • version (string) – URI for Version of Build.

Files

GET /api/v1/file/
Retrieve a list of Files.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/file/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 32084
    },
    "objects": [FILES]
}
Response JSON Object:
 
  • limit (integer) – Number of Files returned.
  • next (string) – URI for next set of Files.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Files.
  • total_count (integer) – Total number of Files.
  • objects (array) – Array of File objects.

File

GET /api/v1/file/{id}/
Parameters:
  • id

    A File id.

    Retrieve a single File.

{
    "absolute_url": "/docs/keystone/en/latest/search.html",
    "id": "332692",
    "name": "search.html",
    "path": "search.html",
    "project": {PROJECT},
    "resource_uri": "/api/v1/file/332692/"
  }
Response JSON Object:
 
  • absolute_url (string) – URI for actual file (not the File object from the API.)
  • id (string) – File id.
  • name (string) – Name of File.
  • path (string) – Name of Path.
  • project (object) – A Project object for the file’s project.
  • resource_uri (string) – URI for File object.

Projects

GET /api/v1/project/
Retrieve a list of Projects.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/project/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 2067
    },
    "objects": [PROJECTS]
}
Response JSON Object:
 
  • limit (integer) – Number of Projects returned.
  • next (string) – URI for next set of Projects.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Projects.
  • total_count (integer) – Total number of Projects.
  • objects (array) – Array of Project objects.

Project

GET /api/v1/project/{id}
Parameters:
  • id

    A Project id.

    Retrieve a single Project.

{
    "absolute_url": "/projects/docs/",
    "analytics_code": "",
    "copyright": "",
    "crate_url": "",
    "default_branch": "",
    "default_version": "latest",
    "description": "Make docs.readthedocs.io work :D",
    "django_packages_url": "",
    "documentation_type": "sphinx",
    "id": "2599",
    "modified_date": "2012-03-12T19:59:09.130773",
    "name": "docs",
    "project_url": "",
    "pub_date": "2012-02-19T18:10:56.582780",
    "repo": "git://github.com/rtfd/readthedocs.org",
    "repo_type": "git",
    "requirements_file": "",
    "resource_uri": "/api/v1/project/2599/",
    "slug": "docs",
    "subdomain": "http://docs.readthedocs.io/",
    "suffix": ".rst",
    "theme": "default",
    "use_virtualenv": false,
    "users": [
        "/api/v1/user/1/"
    ],
    "version": ""
}
Response JSON Object:
 
  • absolute_url (string) – URI for project (not the Project object from the API.)
  • analytics_code (string) – Analytics tracking code.
  • copyright (string) – Copyright
  • crate_url (string) – Crate.io URI.
  • default_branch (string) – Default branch.
  • default_version (string) – Default version.
  • description (string) – Description of project.
  • django_packages_url (string) – Djangopackages.com URI.
  • documentation_type (string) – Either “sphinx” or “sphinx_html”.
  • id (string) – Project id.
  • modified_date (string) – Last modified date.
  • name (string) – Project name.
  • project_url (string) – Project homepage.
  • pub_date (string) – Last published date.
  • repo (string) – URI for VCS repository.
  • repo_type (string) – Type of VCS repository.
  • requirements_file (string) – Pip requirements file for packages needed for building docs.
  • resource_uri (string) – URI for Project.
  • slug (string) – Slug.
  • subdomain (string) – Subdomain.
  • suffix (string) – File suffix of docfiles. (Usually ”.rst”.)
  • theme (string) – Sphinx theme.
  • use_virtualenv (boolean) – Build project in a virtualenv? (True or False)
  • users (array) – Array of readthedocs.org user URIs for administrators of Project.
  • version (string) – DEPRECATED.

Users

GET /api/v1/user/
Retrieve List of Users
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/user/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 3200
    },
    "objects": [USERS]
}
Response JSON Object:
 
  • limit (integer) – Number of Users returned.
  • next (string) – URI for next set of Users.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Users.
  • total_count (integer) – Total number of Users.
  • USERS (array) – Array of User objects.

User

GET /api/v1/user/{id}/
Parameters:
  • id

    A User id.

    Retrieve a single User

{
    "first_name": "",
    "id": "1",
    "last_login": "2010-10-28T13:38:13.022687",
    "last_name": "",
    "resource_uri": "/api/v1/user/1/",
    "username": "testuser"
}
Response JSON Object:
 
  • first_name (string) – First name.
  • id (string) – User id.
  • last_login (string) – Timestamp of last login.
  • last_name (string) – Last name.
  • resource_uri (string) – URI for this user.
  • username (string) – User name.

Versions

GET /api/v1/version/
Retrieve a list of Versions.
{
    "meta": {
        "limit": 20,
        "next": "/api/v1/version/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 16437
    },
    "objects": [VERSIONS]
}
Response JSON Object:
 
  • limit (integer) – Number of Versions returned.
  • next (string) – URI for next set of Versions.
  • offset (integer) – Current offset used for pagination.
  • previous (string) – URI for previous set of Versions.
  • total_count (integer) – Total number of Versions.
  • objects (array) – Array of Version objects.

Version

GET /api/v1/version/{id}
Parameters:
  • id

    A Version id.

    Retrieve a single Version.

{
    "active": false,
    "built": false,
    "id": "12095",
    "identifier": "remotes/origin/zip_importing",
    "project": {PROJECT},
    "resource_uri": "/api/v1/version/12095/",
    "slug": "zip_importing",
    "uploaded": false,
    "verbose_name": "zip_importing"
}
Response JSON Object:
 
  • active (boolean) – Are we continuing to build docs for this version?
  • built (boolean) – Have docs been built for this version?
  • id (string) – Version id.
  • identifier (string) – Identifier of Version.
  • project (object) – A Project object for the version’s project.
  • resource_uri (string) – URI for Version object.
  • slug (string) – String that uniquely identifies a project
  • uploaded (boolean) – Were docs uploaded? (As opposed to being build by Read the Docs.)
  • verbose_name (string) – Usually the same as Slug.

Filtering Examples

Find Highest Version

http://readthedocs.org/api/v1/version/pip/highest/?format=json
GET /api/v1/version/{id}/highest/
Parameters:
  • id

    A Version id.

    Retrieve highest version.

{
    "is_highest": true,
    "project": "Version 1.0.1 of pip (5476)",
    "slug": [
        "1.0.1"
    ],
    "url": "/docs/pip/en/1.0.1/",
    "version": "1.0.1"
}

Compare Highest Version

This will allow you to compare whether a certain version is the highest version of a specific project. The below query should return a 'is_highest': false in the returned dictionary.

http://readthedocs.org/api/v1/version/pip/highest/0.8/?format=json
GET /api/v1/version/{id}/highest/{version}
Parameters:
  • id – A Version id.
  • version

    A Version number or string.

    Retrieve highest version.

{
    "is_highest": false,
    "project": "Version 1.0.1 of pip (5476)",
    "slug": [
        "1.0.1"
    ],
    "url": "/docs/pip/en/1.0.1/",
    "version": "1.0.1"
}