API v2 ====== The Read the Docs API uses :abbr:`REST (Representational State Transfer)`. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure. .. warning:: API v2 is planned to be deprecated soon, though we have not yet set a time frame for deprecation yet. We will alert users with our plans when we do. For now, API v2 is still used by some legacy application operations still, but we highly recommend Read the Docs users use :doc:`API v3 ` instead. Some improvements in :doc:`API v3 ` are: * Token based authentication * Easier to use URLs which no longer use numerical ids * More common user actions are exposed through the API * Improved error reporting See its full documentation at :doc:`/api/v3`. Authentication and authorization -------------------------------- Requests to the Read the Docs public API are for public information only and do not require any authentication. Resources --------- Projects ~~~~~~~~ Projects are the main building block of Read the Docs. Projects are built when there are changes to the code and the resulting documentation is hosted and served by Read the Docs. As an example, this documentation is part of the `Docs project`_ which has documentation at https://docs.readthedocs.io. You can always view your Read the Docs projects in your `project dashboard`_. .. _Docs project: https://readthedocs.org/projects/docs/ .. _project dashboard: https://readthedocs.org/dashboard/ Project list ++++++++++++ .. http:get:: /api/v2/project/ Retrieve a list of all Read the Docs projects. **Example request**: .. prompt:: bash $ curl https://readthedocs.org/api/v2/project/?slug=pip **Example response**: .. sourcecode:: js { "count": 1, "next": null, "previous": null, "results": [PROJECTS] } :>json string next: URI for next set of Projects. :>json string previous: URI for previous set of Projects. :>json integer count: Total number of Projects. :>json array results: Array of ``Project`` objects. :query string slug: Narrow the results by matching the exact project slug Project details +++++++++++++++ .. http:get:: /api/v2/project/(int:id)/ Retrieve details of a single project. .. sourcecode:: js { "id": 6, "name": "Pip", "slug": "pip", "programming_language": "py", "default_version": "stable", "default_branch": "master", "repo_type": "git", "repo": "https://github.com/pypa/pip", "description": "Pip Installs Packages.", "language": "en", "documentation_type": "sphinx_htmldir", "canonical_url": "http://pip.pypa.io/en/stable/", "users": [USERS] } :>json integer id: The ID of the project :>json string name: The name of the project. :>json string slug: The project slug (used in the URL). :>json string programming_language: The programming language of the project (eg. "py", "js") :>json string default_version: The default version of the project (eg. "latest", "stable", "v3") :>json string default_branch: The default version control branch :>json string repo_type: Version control repository of the project :>json string repo: The repository URL for the project :>json string description: An RST description of the project :>json string language: The language code of this project :>json string documentation_type: An RST description of the project :>json string canonical_url: The canonical URL of the default docs :>json array users: Array of ``User`` IDs who are maintainers of the project. :statuscode 200: no error :statuscode 404: There is no ``Project`` with this ID Project versions ++++++++++++++++ .. http:get:: /api/v2/project/(int:id)/active_versions/ Retrieve a list of active versions (eg. "latest", "stable", "v1.x") for a single project. .. sourcecode:: js { "versions": [VERSION, VERSION, ...] } :>json array versions: Version objects for the given ``Project`` See the :ref:`Version detail ` call for the format of the ``Version`` object. Versions ~~~~~~~~ Versions are different versions of the same project documentation The versions for a given project can be viewed in a project's version screen. For example, here is the `Pip project's version screen`_. .. _Pip project's version screen: https://readthedocs.org/projects/pip/versions/ Version list ++++++++++++ .. http:get:: /api/v2/version/ Retrieve a list of all Versions for all projects .. sourcecode:: js { "count": 1000, "previous": null, "results": [VERSIONS], "next": "https://readthedocs.org/api/v2/version/?limit=10&offset=10" } :>json string next: URI for next set of Versions. :>json string previous: URI for previous set of Versions. :>json integer count: Total number of Versions. :>json array results: Array of ``Version`` objects. :query string project__slug: Narrow to the versions for a specific ``Project`` :query boolean active: Pass ``true`` or ``false`` to show only active or inactive versions. By default, the API returns all versions. .. _api-version-detail: Version detail ++++++++++++++ .. http:get:: /api/v2/version/(int:id)/ Retrieve details of a single version. .. sourcecode:: js { "id": 1437428, "slug": "stable", "verbose_name": "stable", "built": true, "active": true, "type": "tag", "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914", "privacy_level": "public", "downloads": { "pdf": "//readthedocs.org/projects/pip/downloads/pdf/stable/", "htmlzip": "//readthedocs.org/projects/pip/downloads/htmlzip/stable/", "epub": "//readthedocs.org/projects/pip/downloads/epub/stable/" }, "project": {PROJECT}, } :>json integer id: The ID of the version :>json string verbose_name: The name of the version. :>json string slug: The version slug. :>json string built: Whether this version has been built :>json string active: Whether this version is still active :>json string type: The type of this version (typically "tag" or "branch") :>json string identifier: A version control identifier for this version (eg. the commit hash of the tag) :>json array downloads: URLs to downloads of this version's documentation :>json object project: Details of the ``Project`` for this version. :statuscode 200: no error :statuscode 404: There is no ``Version`` with this ID 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 screen for a project. For example, here is `Pip's build screen`_. .. _Pip's build screen: https://readthedocs.org/projects/pip/builds/ Build list ++++++++++ .. http:get:: /api/v2/build/ Retrieve details of builds ordered by most recent first **Example request**: .. prompt:: bash $ curl https://readthedocs.org/api/v2/build/?project__slug=pip **Example response**: .. sourcecode:: js { "count": 100, "next": null, "previous": null, "results": [BUILDS] } :>json string next: URI for next set of Builds. :>json string previous: URI for previous set of Builds. :>json integer count: Total number of Builds. :>json array results: Array of ``Build`` objects. :query string project__slug: Narrow to builds for a specific ``Project`` :query string commit: Narrow to builds for a specific ``commit`` Build detail ++++++++++++ .. http:get:: /api/v2/build/(int:id)/ Retrieve details of a single build. .. sourcecode:: js { "id": 7367364, "date": "2018-06-19T15:15:59.135894", "length": 59, "type": "html", "state": "finished", "success": true, "error": "", "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30", "docs_url": "http://pip.pypa.io/en/latest/", "project": 13, "project_slug": "pip", "version": 3681, "version_slug": "latest", "commands": [ { "description": "", "start_time": "2018-06-19T20:16:00.951959", "exit_code": 0, "build": 7367364, "command": "git remote set-url origin git://github.com/pypa/pip.git", "run_time": 0, "output": "", "id": 42852216, "end_time": "2018-06-19T20:16:00.969170" }, ... ], ... } :>json integer id: The ID of the build :>json string date: The ISO-8601 datetime of the build. :>json integer length: The length of the build in seconds. :>json string type: The type of the build (one of "html", "pdf", "epub") :>json string state: The state of the build (one of "triggered", "building", "installing", "cloning", or "finished") :>json boolean success: Whether the build was successful :>json string error: An error message if the build was unsuccessful :>json string commit: A version control identifier for this build (eg. the commit hash) :>json string docs_url: The canonical URL of the build docs :>json integer project: The ID of the project being built :>json string project_slug: The slug for the project being built :>json integer version: The ID of the version of the project being built :>json string version_slug: The slug for the version of the project being built :>json array commands: Array of commands for the build with details including output. :statuscode 200: no error :statuscode 404: There is no ``Build`` with this ID Some fields primarily used for UI elements in Read the Docs are omitted. Embed ~~~~~ .. http:get:: /api/v2/embed/ Retrieve HTML-formatted content from documentation page or section. **Example request**: .. prompt:: bash $ curl https://readthedocs.org/api/v2/embed/?project=docs&version=latest&doc=features&path=features.html or .. prompt:: bash $ curl https://readthedocs.org/api/v2/embed/?url=https://docs.readthedocs.io/en/latest/features.html **Example response**: .. sourcecode:: js { "content": [ "
\n

Read the Docs..." ], "headers": [ { "Read the Docs features": "#" }, { "Automatic Documentation Deployment": "#automatic-documentation-deployment" }, { "Custom Domains & White Labeling": "#custom-domains-white-labeling" }, { "Versioned Documentation": "#versioned-documentation" }, { "Downloadable Documentation": "#downloadable-documentation" }, { "Full-Text Search": "#full-text-search" }, { "Open Source and Customer Focused": "#open-source-and-customer-focused" } ], "url": "https://docs.readthedocs.io/en/latest/features", "meta": { "project": "docs", "version": "latest", "doc": "features", "section": "read the docs features" } } :>json string content: HTML content of the section. :>json object headers: section's headers in the document. :>json string url: URL of the document. :>json object meta: meta data of the requested section. :query string project: Read the Docs project's slug. :query string doc: document to fetch content from. :query string version: *optional* Read the Docs version's slug (default: ``latest``). :query string section: *optional* section within the document to fetch. :query string path: *optional* full path to the document including extension. :query string url: full URL of the document (and section) to fetch content from. .. note:: You can call this endpoint by sending at least ``project`` and ``doc`` *or* ``url`` attribute. Undocumented resources and endpoints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are some undocumented endpoints in the API. These should not be used and could change at any time. These include: * Endpoints for returning footer and version data to be injected into docs. (``/api/v2/footer_html``) * Endpoints used for advertising (``/api/v2/sustainability/``) * Any other endpoints not detailed above.