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" }
File Search¶
http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper
- GET /api/v1/file/search/?q={search_term}¶
Path arguments: search_term – Perform search with this term.
- Retrieve a list of File objects that contain the search term.¶
{ "objects": [ { "absolute_url": "/docs/python-guide/en/latest/scenarios/virtualenvs/index.html", "id": "375539", "name": "index.html", "path": "scenarios/virtualenvs/index.html", "project": { "absolute_url": "/projects/python-guide/", "analytics_code": null, "copyright": "Unknown", "crate_url": "", "default_branch": "", "default_version": "latest", "description": "[WIP] Python best practices...", "django_packages_url": "", "documentation_type": "sphinx_htmldir", "id": "530", "modified_date": "2012-03-13T01:05:30.191496", "name": "python-guide", "project_url": "", "pub_date": "2011-03-20T19:40:03.599987", "repo": "git://github.com/kennethreitz/python-guide.git", "repo_type": "git", "requirements_file": "", "resource_uri": "/api/v1/project/530/", "slug": "python-guide", "subdomain": "http://python-guide.readthedocs.org/", "suffix": ".rst", "theme": "kr", "use_virtualenv": false, "users": [ "/api/v1/user/130/" ], "version": "" }, "resource_uri": "/api/v1/file/375539/", "text": "...<span class=\"highlighted\">virtualenvwrapper</span>\n..." }, ... ] }
Anchor Search¶
http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv
- GET /api/v1/file/anchor/?q={search_term}¶
Path arguments: search_term – Perform search of files containing anchor text with this term.
- Retrieve a list of absolute URIs for files that contain the search term.¶
{ "objects": [ "http//django-fab-deploy.readthedocs.org/en/latest/...", "http//dimagi-deployment-tools.readthedocs.org/en/...", "http//openblock.readthedocs.org/en/latest/install/base_install.html#virtualenv", ... ] }