Docs/API Reference

API Reference

DocsCI REST API

The DocsCI API lets you queue runs, retrieve findings, manage projects, and integrate DocsCI into any CI/CD system — not just GitHub Actions.

Base URLhttps://snippetci.com/api

Authentication

All API requests require a bearer token. Generate a token in your Dashboard → Settings → API Tokens. Pass it in the Authorization header:

curl https://snippetci.com/api/runs/queue \
-H "Authorization: Bearer $DOCSCI_TOKEN" \
-H "Content-Type: application/json" \
-d '{"repo":"owner/repo","sha":"abc123"}'

Endpoints

POST/api/runs/queueQueue a documentation run

Triggers a new DocsCI run against a given repository commit. Returns a run ID you can poll for results.

Request body

Field	Type	Required	Description
repo	string	required	GitHub repository in owner/repo format.
sha	string	optional	Git commit SHA to check. Defaults to the HEAD of the default branch.
branch	string	optional	Branch name. Used if sha is not provided.
pr_number	integer	optional	Pull request number. When provided, DocsCI posts inline PR comments.
checks	string[]	optional	Subset of checks to run: snippets, drift, accessibility, copy. Defaults to all.

Response

{
  "id": "run_01HX...",
  "status": "queued",
  "repo": "owner/repo",
  "sha": "abc123",
  "created_at": "2026-04-14T10:00:00Z",
  "url": "https://snippetci.com/runs/run_01HX..."
}

GET/api/runs/{runId}Get a run

Retrieve the current status and findings summary for a run.

Response

{
  "id": "run_01HX...",
  "status": "completed",  // queued | running | completed | failed
  "repo": "owner/repo",
  "sha": "abc123",
  "created_at": "2026-04-14T10:00:00Z",
  "completed_at": "2026-04-14T10:02:34Z",
  "summary": {
    "total": 42,
    "passed": 39,
    "failed": 3,
    "skipped": 0
  }
}

GET/api/runsList runs

Returns paginated run history for the authenticated user's organization.

Query parameters

Param	Type	Description
limit	integer	Max results (1–100, default 20).
offset	integer	Pagination offset.
repo	string	Filter by repository (owner/repo).
status	string	Filter by status: queued \| running \| completed \| failed.

Response

{
  "runs": [ { "id": "...", "status": "completed", ... } ],
  "total": 128,
  "limit": 20,
  "offset": 0
}

GET/api/findingsGet findings for a run

Returns detailed findings (failed checks) for a completed run.

Query parameters

Param	Type	Description
run_id	string	Required. The run ID to fetch findings for.
kind	string	Filter by finding type: snippet \| drift \| accessibility \| copy.

Response

{
  "findings": [
    {
      "id": "fnd_01HX...",
      "kind": "snippet",
      "severity": "error",
      "file": "docs/quickstart.md",
      "line": 42,
      "message": "Python snippet exited with code 1: ModuleNotFoundError: No module named 'requests'",
      "snippet": "import requests\nrequests.get('https://...')",
      "suggested_fix": "import httpx\nhttpx.get('https://...')"
    }
  ]
}

POST/api/tokensCreate an API token

Generates a new API token scoped to the authenticated user's organization.

Request body

Field	Type	Required	Description
name	string	required	Human-readable label for this token (e.g. 'GitHub Actions prod').
expires_at	ISO 8601	optional	Optional expiry date. Tokens without expiry are valid until revoked.

Response

{
  "id": "tok_01HX...",
  "name": "GitHub Actions prod",
  "token": "dci_live_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-04-14T10:00:00Z",
  "expires_at": null
}

// Note: the token value is returned only once. Store it securely.

GET/api/healthHealth check

Returns service status. No authentication required. Use this for uptime monitoring.

Response

{
  "status": "ok",
  "db": "ok",
  "auth": "ok",
  "uptime": 86400,
  "version": "0.9.0"
}

Error responses

All errors return JSON with an error field.

400

Bad Request — invalid or missing parameters.

401

Unauthorized — missing or invalid API token.

403

Forbidden — token lacks permission for this resource.

404

Not Found — run, finding, or resource doesn't exist.

429

Too Many Requests — rate limit exceeded. Retry after the Retry-After header.

500

Internal Server Error — something went wrong on our side.

Rate limits

Free60 requests / minute per token

Pro600 requests / minute per token

EnterpriseCustom — contact sales

Versioning

The current API is v1 (implicit — no version prefix required in URLs). When breaking changes are introduced, a new version prefix will be added (e.g. /api/v2/...) and the old version will remain available for 12 months with deprecation notices.

Need help with the API?

Email us at hello@snippetci.com or open an issue on GitHub.

Back to Getting Started →