API Reference

This page documents the API as we're designing it. Endpoints land progressively — the CLI covers everything described here today; the HTTP surface is rolling out behind a feature flag and gets opened on request. Email api@quilldocs.ai if you need a specific endpoint sooner.

[ posture ]

A small API, the way you'd want it.

Token auth, scoped

API tokens scope to a workspace and a set of actions (read, write, publish, admin). Tokens are reissuable and revocable from the portal. No long-lived secrets in your CI logs.

Idempotency on writes

Every POST and PATCH accepts an Idempotency-Key header. Retries are safe; the same key returns the same result for 24 hours.

Versioned via URL prefix

All endpoints live under /v1/. We don't break v1 — additive changes only. When the shape needs a meaningful break, the v2 prefix lights up and v1 sticks around for at least 12 months.

Rate limits with retry hints

Default 600 requests / 5 minutes per token. Headers tell you what's left. On 429 we include theRetry-After seconds — exponential backoff is enough, no special handling required.

[ surface ]

Four resources, the actions you'd expect.

Workspacesread · write

Tenants of the platform. One workspace per deploy. List, create, fetch, soft-delete. POST /v1/workspaces, GET /v1/workspaces/{id}, DELETE /v1/workspaces/{id}.

Articlesread · write · publish

The generated artifacts — help-center walkthroughs, dev-doc pages, changelog entries, blog posts. List, fetch, regenerate, publish. GET /v1/workspaces/{ws}/articles, POST /v1/articles/{id}/publish, POST /v1/articles/{id}/regenerate.

Runsread · trigger

Pipeline executions. Each run has status, timing, artifacts, and a structured log. POST /v1/workspaces/{ws}/runs to kick one off, GET /v1/runs/{id} to follow it, GET /v1/runs/{id}/log for the structured event stream.

Webhook subscriptionsread · write

Create and manage webhook delivery endpoints. CRUD on the subscription, plus an endpoint to POST /v1/webhooks/{id}/replay any past event. See webhook events for the payload shapes.

[ example ]

Trigger a pipeline run.

Kick off a pipeline run against a feature. Pass an Idempotency-Key so retries are safe.

curl -X POST https://api.quilldocs.ai/v1/workspaces/ws_abc/runs \
  -H "Authorization: Bearer $QUILL_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_id": "flows_create",
    "tier": "single",
    "notify_on_complete": true
  }'

Response — the new run, with a streaming log URL you can poll.

{
  "id":        "run_01HMBXY...",
  "status":    "queued",
  "feature_id": "flows_create",
  "log_url":   "https://api.quilldocs.ai/v1/runs/run_01HMBXY.../log",
  "created_at": "2026-06-10T03:14:22Z"
}

Programmatic access to every Quill primitive.