REST API

Programmatic access to your workspace. Available on the Pro and Team plans. All endpoints live under https://docs-keeper.com/api/v1 and are authenticated with a bearer token from Settings → API keys.

Authentication

Pass your token as a bearer header. Tokens belong to a single workspace. Free and Starter keys are rejected with 403 — the REST API is a Pro+ feature.

curl https://docs-keeper.com/api/v1/runs \
  -H "Authorization: Bearer dk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Scopes

Each key is created read-only or full access (chosen in Settings → API keys). Read-only keys carry read:runs, read:repos, read:voice; full keys add the write:* and analyze:diff scopes. A call missing the scope an endpoint needs returns 403.

Endpoints

Method & path	Scope	Description
`GET /api/v1/repos`	`read:repos`	List connected repositories.
`GET /api/v1/runs`	`read:runs`	List doc-PR runs, newest first. Filters below.
`GET /api/v1/runs/:id`	`read:runs`	Fetch one run with token usage, cost, and per-file generations.
`GET /api/v1/runs/:id/generations`	`read:runs`	Per-file generations for a run (path, rationale, validation status).
`POST /api/v1/runs/:id/replay`	`write:runs`	Re-run an existing run.
`POST /api/v1/runs/trigger`	`write:runs`	Queue a run for a merged PR. Body: `{ "repo": "owner/name", "pr_number": 123 }`.
`POST /api/v1/analyze-diff`	`analyze:diff`	AI diff → doc suggestions. Works without the GitHub App. Body: `{ "diff": "...", "context"?: "...", "lang"?: "..." }` (diff ≤ 50 KB).
`POST /api/v1/voice/analyze`	`read:voice`	Check text against your brand-voice fingerprint. Body: `{ "text": "..." }`.
`GET /api/v1/scans`	`read:runs`	List security scans (powers the browser extension).

List filters & pagination

GET /runs accepts repo (owner/name), status (queued, running, succeeded, needs_review, failed, skipped), since (ISO 8601), and limit (1–100, default 25). Paginate with the opaque cursor returned as next_cursor.

Response shape

{
  "data": {
    "id": "01J5...",
    "status": "succeeded",
    "pr_number": 847,
    "pr_title": "Add /v2/users/provision endpoint",
    "repo_full_name": "acme-corp/core-api",
    "input_tokens": 12345,
    "output_tokens": 2400,
    "cache_read_tokens": 8000,
    "cost_usd_cents": 4,
    "generated_pr_number": 848,
    "created_at": "2026-05-17T10:42:00Z",
    "finished_at": "2026-05-17T10:42:53Z"
  }
}

List endpoints wrap results as { "data": [...], "next_cursor": "...", "has_more": true }.

Rate limits

Pro: 3,000 requests / hour
Team: 10,000 requests / hour

Fixed-window per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceed the limit and you get a 429 with a Retry-After header.