Read the Docs Project Manager

Use the Read the Docs API to create and manage projects. This skill covers the core project lifecycle tasks that are commonly needed for setup and verification.

Required inputs

•
RTD host in RTD_HOST
- •Community: https://app.readthedocs.org
- •Business: https://app.readthedocs.com
•API token available in RTD_TOKEN (preferred) or provided by the user

Quick workflow

•Confirm host and token source.
•Collect project inputs (name, slug, repo URL, repo type).
•Create the project via API.
•Trigger a build or sync versions if needed.
•Poll the latest build status.

API basics

Base URL:

code

${RTD_HOST}/api/v3/

All authenticated requests:

code

-H "Authorization: Token $RTD_TOKEN"

Common tasks

1) List remote repositories (optional)

Use this when you need to verify repo access or pick a repo from integrations.

code

GET /api/v3/remote/repositories/

Example:

bash

curl -s -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/remote/repositories/"

2) Create a project

code

POST /api/v3/projects/

Minimal body:

json

{
  "name": "Project Name",
  "slug": "project-slug",
  "repository": {
    "url": "https://github.com/org/repo",
    "type": "git"
  }
}

Example:

bash

curl -s -X POST "${RTD_HOST}/api/v3/projects/" \
  -H "Authorization: Token $RTD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Project Name","slug":"project-slug","repository":{"url":"https://github.com/org/repo","type":"git"}}'

3) Sync versions

code

POST /api/v3/projects/{slug}/sync-versions/

bash

curl -s -X POST \
  -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/projects/project-slug/sync-versions/"

4) Trigger a build

code

POST /api/v3/projects/{slug}/versions/{version}/builds/

bash

curl -s -X POST \
  -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/projects/project-slug/versions/latest/builds/"

5) Check latest build status

code

GET /api/v3/projects/{slug}/builds/?limit=1

bash

curl -s -H "Authorization: Token $RTD_TOKEN" \
  "${RTD_HOST}/api/v3/projects/project-slug/builds/?limit=1"

Notes

•Use the community host for public RTD, and your Business host for private instances.
•Do not print or log token values in responses.
•If project creation fails, confirm the slug is available and the repo URL is reachable.