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 ( if you have feature requests.

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.

The API is written in Tastypie, which provides a nice ability to browse the API from your browser. If you go to 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:

from __future__ import print_function
import slumber
import json

show_objs = True
api = slumber.API(base_url='')

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

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

Alternatively you can try with the following value:

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

# get a specfic build
val =

# get the build of a specific project.
val ='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()

Example of adding a user to a project

You can use the api to add user to a project, to authenticate with slumber, use the following:

from __future__ import print_function
import slumber

USERNAME = 'eric'
PASSWORD = 'test'

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

api = slumber.API(base_url='', auth=(USERNAME,PASSWORD))
from __future__ import print_function

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'][:]}

print("Adding %s to %s" % (user_objects['username'], project_objects['slug']))

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 | python -m json.tool


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/"
  • list_endpoint (string) – API endpoint for resource.
  • schema (string) – API endpoint for schema of resource.


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]
  • 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.


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/"
  • 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.


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]
  • 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.


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/"
  • 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.


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]
  • 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.


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 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://",
    "repo_type": "git",
    "requirements_file": "",
    "resource_uri": "/api/v1/project/2599/",
    "slug": "docs",
    "subdomain": "",
    "suffix": ".rst",
    "theme": "default",
    "use_virtualenv": false,
    "users": [
    "version": ""
  • 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) – URI.
  • default_branch (string) – Default branch.
  • default_version (string) – Default version.
  • description (string) – Description of project.
  • django_packages_url (string) – 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 user URIs for administrators of Project.
  • version (string) – DEPRECATED.


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]
  • 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.


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"
  • 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.


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]
  • 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.


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"
  • 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
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": [
    "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.
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": [
    "url": "/docs/pip/en/1.0.1/",
    "version": "1.0.1"