Read the Docs Public API

We have a limited public API that is available for you to get data out of the site. This page will only show a few of the basic parts, please file a ticket or ping us on IRC (#readthedocs on Freenode (chat.freenode.net)) if you have feature requests.

This document covers the read-only API provided. We have plans to create a read/write API, so that you can easily automate interactions with your project.

The API is written in Tastypie, which provides a nice ability to browse the API from your browser. If you go to http://readthedocs.org/api/v1/?format=json and just poke around, you should be able to figure out what is going on.

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:

import slumber
import json

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

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

#val = api.build(49252).get()
#val = api.build.get(project__slug='read-the-docs')

#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()

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

Example of adding a user to a project

import slumber

USERNAME = 'eric'
PASSWORD = 'test'

user_to_add = 'coleifer'
project_slug = 'read-the-docs'

api = slumber.API(base_url='http://readthedocs.org/api/v1/', authentication={'name': USERNAME, 'password': PASSWORD})

project = api.project.get(slug=project_slug)
user = api.user.get(username=user_to_add)
project_objects = project['objects'][0]
user_objects = user['objects'][0]

data = {'users': project_objects['users'][:]}
data['users'].append(user_objects['resource_uri'])

print "Adding %s to %s" % (user_objects['username'], project_objects['slug'])
api.project(project_objects['id']).put(data)

project2 = api.project.get(slug=project_slug)
project2_objects = project2['objects'][0]
print "Before users: %s" % project_objects['users']
print "After users: %s" % project2_objects['users']

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/"
    }
}
Data:
  • 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]
}
Data:
  • 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}/
Path arguments: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/"
}
Data:
  • 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]
}
Data:
  • 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}/
Path arguments: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/"
  }
Data:
  • 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]
}
Data:
  • 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}
Path arguments: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.org 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.org/",
    "suffix": ".rst",
    "theme": "default",
    "use_virtualenv": false,
    "users": [
        "/api/v1/user/1/"
    ],
    "version": ""
}
Data:
  • 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]
}
Data:
  • 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}/
Path arguments: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"
}
Data:
  • 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]
}
Data:
  • 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}
Path arguments: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"
}
Data:
  • 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/
Path arguments: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}
Path arguments:
  • 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"
}