REST API

CompassDocs ships a small, stable REST API at /api/v1 for scripting and integrations: CI jobs that update runbooks, exporters, dashboards, or anything else that shouldn’t need a browser session.

Authentication

Every request needs a personal access token in the Authorization header:

curl -H "Authorization: Bearer cdk_…" https://docs.example.com/api/v1/me

Create tokens under your name → Manage account → API tokens. Each token has scopes chosen at creation:

Scope	Grants
read	All GET endpoints — documents, spaces, search.
write	Creating, editing, and trashing documents.

A token can never do more than the person it belongs to: role, space access, and the approval workflow all still apply. Uncheck Allow writes when creating a token to mint a read-only one — enough for search and exports, and the safer default for anything that only consumes content. (The Claude connector needs a read + write token.)

Requests are rate-limited to 120/minute per user; over the limit you get 429. Tokens are shown once at creation, stored only as a hash, and revocable any time from the same screen.

Endpoints

GET /api/v1/me

Token introspection — the user it acts as, their role, and the token’s scopes.

GET /api/v1/spaces

Spaces visible to the token’s user, with slugs (used as the space parameter elsewhere), visibility, and document counts.

GET /api/v1/documents

List documents, newest first. Query parameters:

Parameter	Meaning
space	A space slug (e.g. engineering).
status	published or draft — drafts are visible to editors and up.
limit / offset	Paging; limit caps at 100 (default 25).

Returns {items, total, limit, offset}. List items omit content; fetch a single document for the full body.

POST /api/v1/documents

Create a document (needs write + the editor role + edit rights in the space):

curl -X POST https://docs.example.com/api/v1/documents \
  -H "Authorization: Bearer cdk_…" -H "Content-Type: application/json" \
  -d '{"space":"engineering","title":"Deploy runbook","content":"…",
       "type":"sop","tags":["deploy"],"status":"published"}'

type is one of sop | technical | policy | knowledge (default knowledge). In a strict-approval workspace, an editor asking for published gets a draft back with a note — publishing still goes through review, same as the app.

GET /api/v1/documents/:id

One document, content included.

PATCH /api/v1/documents/:id

Partial update — send any of title, content, summary, tags, type, status, plus an optional note (used as the version note). If the change touches a published document and the token’s user can’t publish, the change is queued as a change request and you get 202 {pending: true, change_request_id} — nothing goes live until an approver signs off.

DELETE /api/v1/documents/:id

Moves the document to the Trash (restorable in the app; permanent deletion follows the workspace retention setting).

GET /api/v1/search?q=

The same hybrid search as the app — full-text always, fused with semantic retrieval when an embeddings provider is configured — including the type: tag: space: author: status: operators:

curl -H "Authorization: Bearer cdk_…" \
  "https://docs.example.com/api/v1/search?q=failover+space:engineering"

Snippets come back as plain text.

Errors

Errors are JSON with a human-readable message: 401 (missing/invalid token), 403 (missing scope, role, or edit rights), 404 (not found — including documents outside the user’s space scope), 429 (rate limit), 400 (malformed input).

Beyond REST

For AI-driven use, the Claude connector exposes the full editing surface over MCP — the REST API is the better fit for scripts and conventional integrations.