Collaboration API
Reviews, approvals, scheduled publishing, style rules, glossary, and access control endpoints.
The collaboration API powers the dashboard's team workflow features. All endpoints require authentication and are relative to /v1/projects/{projectId}. In the dashboard these features live under Workflow — see Workflow for the feature-level guide.
Authentication alone is not enough. Every endpoint in this API is scoped to the
project's organization: you must be a member of the org that owns
{projectId}. A project you cannot see returns 404, and one you can see but
are not a member of returns 403 with the forbidden code — see
Errors.
Membership in {projectId} does not carry over to the row named in the rest
of the path. Every endpoint that takes a second id — a rule, term, list,
review, schedule, gate, approval or preview — matches on that id and the
project. An id that belongs to a different project is indistinguishable from
one that does not exist, and returns 404.
Roles
Every endpoint needs a signed-in member of the workspace, with a session JWT — API keys are refused with 401. No endpoint here is plan-gated. The Role column below gives the minimum workspace role (owner > admin > member); admin means admin or owner. Calling an admin endpoint as a member returns 403 forbidden with details.requiredRole and details.currentRole — see Role errors.
Reviews, approvals and schedules also have per-item rules, described under each section. Those depend on who you are relative to the item, not only on your role.
A request body or query that fails schema validation — a missing field, a value out of range, an unknown enum value — gets 400 validation_error in the standard envelope, with each problem in details.issues — see Validation errors.
Reviews
| Endpoint | Role | Description |
|---|---|---|
GET /reviews | member | List review requests |
POST /reviews | member | Create a review request and assign a reviewer |
PATCH /reviews/{reviewId} | reviewer or admin | Set status to approved, rejected, or merged |
reviewerId) must be a member of the workspace, and cannot be you. Otherwise: 400 invalid_reviewer.403 forbidden with details.currentRole.403 self_approval. You can still mark your own review rejected or merged if you are an admin.Approval Gates & Approvals
Require sign-off before certain pages can be published.
| Endpoint | Role | Description |
|---|---|---|
GET /approval-gates | member | List every gate, enabled or not. ?enabled=true|false filters |
POST /approval-gates | admin | Create a gate |
PATCH /approval-gates/{gateId} | admin | Edit a gate, or switch it on or off |
DELETE /approval-gates/{gateId} | admin | Delete a gate with no pending approvals |
GET /approvals | member | List pending approvals |
POST /approvals | member | Request approval against one of this project's gates, with an optional title |
POST /approvals/{id}/approve | gate's approver roles | Approve |
POST /approvals/{id}/reject | gate's approver roles | Reject with a reason |
approverRoles lists the roles that may decide its approvals. Each entry is a minimum, so ["member"] admits everyone and ["admin"] admits admins and owners. A gate with no recognised roles, or no gate at all, falls back to admin. A caller below every listed role gets 403 role_not_allowed, with details.allowed and details.currentRole.403 self_approval.409 already_approved. requiredApprovers counts distinct people.approved or rejected it is closed. A later approve or reject returns 409 approval_closed with details.status. This also covers losing a race to someone who decided first.POST /approvals with a gateId from another project returns 404.GET /approval-gates returns every gate — disabled ones included — oldest first. Earlier releases returned only enabled gates; filter with ?enabled=true if you relied on that. Any other enabled value is ignored.POST /approvals accepts an optional title (1–300 characters) to show in the approvals list. GET /approvals returns it on each row as title, or null.409 gate_in_use with details.pending. Switch it off with enabled: false instead, or decide the approvals first.Scheduled Publishing
| Endpoint | Role | Description |
|---|---|---|
GET /schedules | member | List schedules in every status. ?status= filters |
POST /schedules | member | Schedule content to go live at a future time |
PATCH /schedules/{scheduleId} | creator or admin | Change the time, content or commit message |
DELETE /schedules/{scheduleId} | creator or admin | Cancel a schedule |
GET /schedules returns every status — scheduled, publishing, published, cancelled and failed — soonest scheduledFor first, up to 200 rows. Earlier releases returned only scheduled rows; pass ?status=scheduled if you relied on that. ?status= takes a comma-separated list, e.g. ?status=published,failed; an unknown status returns 400 validation_error with details.allowed. Each row includes commitSha, null until the schedule is published.
Only the person who created a schedule, or a workspace admin, can edit or cancel it. Anyone else gets 403 forbidden. A schedule that has already published, failed or been cancelled cannot be edited or cancelled: 409 not_scheduled, with details.status.
Due schedules are published within about a minute of their time: the content is committed (or saved, for a project written in Syntext) and a build starts. While it runs the row is publishing; it then moves to published with commitSha, or to failed with errorMessage. ?status= doesn't accept publishing.
Previews
Preview records track pull-request preview deployments — branch, base branch, author, status and URL. They are not shareable links: there is no password or expiry.
| Endpoint | Role | Description |
|---|---|---|
GET /previews | member | List previews |
POST /previews | member | Create a preview record |
PATCH /previews/{previewId} | member | Set a preview's status |
Style Rules & Linter
| Endpoint | Role | Description |
|---|---|---|
GET /linter | member | Get linter configuration |
PUT /linter | admin | Update linter configuration |
GET /style-rules | member | List custom style rules |
POST /style-rules | admin | Add a rule (terminology, tone, banned phrases) |
PATCH /style-rules/{ruleId} · DELETE /style-rules/{ruleId} | admin | Update / remove |
POST /lint | member | Lint one page's content on demand |
POST /lint-runs | admin | Lint every page in the repository |
GET /lint-runs/latest | member | The newest completed project-wide run and its counts |
GET /lint-results | member | Latest lint results |
POST /lint/auto-fix | admin | Apply automatic fixes |
A project-wide run replaces the previous run's findings in GET /lint-results. Results saved for a single page through POST /lint are kept.
Glossary
| Endpoint | Role | Description |
|---|---|---|
GET /glossary | member | List terms, alphabetically, with meta.total |
POST /glossary | admin | Add a term, with an optional definition |
POST /glossary/import | admin | Import terms from CSV |
PATCH /glossary/{termId} · DELETE /glossary/{termId} | admin | Update / remove |
GET /glossary returns { data, meta: { total } }, where total is the project's term count. Pass ?limit (1–500) and ?offset (0 or more) to page through data; meta then also echoes limit and offset. Without limit, every term is returned.
definition is optional on POST /glossary and is stored as an empty string when omitted. PATCH /glossary/{termId} accepts "" to clear it.
Glossary terms are underlined with hover definitions on the deployed doc site and enforced by the linter for consistent terminology.
A term is unique within a project. POST /glossary with a term the project
already has returns 409 with code term_exists, and details.term naming
it; the stored definition is left untouched. Use
PATCH /glossary/{termId} to change an existing term instead. Two different
projects may each define the same term.
Content Ownership
| Endpoint | Role | Description |
|---|---|---|
GET /ownership | member | Page → owner assignments, each with lastChangedAt |
POST /ownership | admin | Assign an owner to a path pattern |
GET /ownership/stale | member | Owned pages that have gone stale |
GET /ownership/summary | member | Coverage, stale count, unowned pages and alert settings |
PATCH /ownership/settings | admin | Stale threshold and alert destinations |
Each GET /ownership row carries lastChangedAt: when the page last changed, as recorded by builds and content-health checks, or null when unknown. Paths match loosely — /getting-started and getting-started.mdx are the same page.
The alert settings drive a weekly run (Mondays 09:00 UTC) that emails each owner their stale pages and posts one message to the saved Slack channel — see Stale-page alerts.
Access Control
| Endpoint | Role | Description |
|---|---|---|
GET /access-rules · POST /access-rules | admin | Path-based access rules |
PATCH /access-rules/{ruleId} · DELETE /access-rules/{ruleId} | admin | Update / remove |
GET /ip-allowlists · POST /ip-allowlists | admin | IP allowlists for gated docs |
PATCH /ip-allowlists/{listId} · DELETE /ip-allowlists/{listId} | admin | Update / remove |
POST /access-check | member | Test whether a visitor would have access |
GET /access-logs | admin | Access audit log |
Access rules, IP allowlists and access logs are admin-only even to read.
PATCH /access-rules/{ruleId} and PATCH /ip-allowlists/{listId} return
404 when the id does not belong to the project in the path. Treat a 404
as "nothing changed" — earlier releases answered 200 with a null body in that
case, which read as a successful edit.
Doc sites don't enforce access rules or IP allowlists yet. These endpoints store them, and POST /access-check evaluates access rules, but the deployed site never consults either when it serves a page. Site visibility and audience gating are enforced.
Access rule passwords
A rule with accessType: "password" takes its password as password (1–200 characters) on POST /access-rules and PATCH /access-rules/{ruleId}. It is stored only as an argon2id hash and never returned: every rule in a response carries hasPassword: boolean instead, and no passwordHash field.
passwordHash is still accepted as a deprecated alias with the same meaning — send the plaintext there, not a hash. If you send both, password wins.PATCH, leaving both out keeps the stored password.POST /access-check with a password checks it against the stored hash. Earlier releases denied every password rule ("Password required") whatever was sent.Access rule navigation
POST /access-rules and PATCH /access-rules/{ruleId} accept an optional navigation string, and every rule returned by GET, POST and PATCH includes navigation: string | null. It is a short display label for how pages matching the rule should appear in navigation, such as "Shown with lock" or "Hidden from search".
400.null on PATCH to clear it. Omitting it leaves the stored value unchanged.Access log entries
Each entry from GET /access-logs (newest first; optional pagePath and limit query parameters, default limit 100) includes:
| Field | Type | Description |
|---|---|---|
who | string | null | The signed-in reader's name, else their email, else the name of the audience profile whose token was used, else null for an anonymous reader |
audienceProfileId | string | null | The audience profile whose access token was presented, if any |
Alongside id, projectId, pagePath, userId, visitorId, accessMethod, ipAddress, granted, deniedReason and createdAt.
Doc-site page views are not written to the access log yet, so GET /access-logs currently returns an empty list.
For audience-based content gating (partner tiers, logged-in users), see Audiences and the Audience Gating guide.