/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API API Reference Collaboration API

Collaboration API

Reviews, approvals, scheduled publishing, style rules, glossary, and access control endpoints.

9 min read

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.

Note

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.

Note

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

EndpointRoleDescription
GET /reviewsmemberList review requests
POST /reviewsmemberCreate a review request and assign a reviewer
PATCH /reviews/{reviewId}reviewer or adminSet status to approved, rejected, or merged
•
The reviewer (reviewerId) must be a member of the workspace, and cannot be you. Otherwise: 400 invalid_reviewer.
•
Only the assigned reviewer or a workspace admin can decide a review. Anyone else gets 403 forbidden with details.currentRole.
•
Nobody, admins included, can approve a review they requested: 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.

EndpointRoleDescription
GET /approval-gatesmemberList every gate, enabled or not. ?enabled=true|false filters
POST /approval-gatesadminCreate a gate
PATCH /approval-gates/{gateId}adminEdit a gate, or switch it on or off
DELETE /approval-gates/{gateId}adminDelete a gate with no pending approvals
GET /approvalsmemberList pending approvals
POST /approvalsmemberRequest approval against one of this project's gates, with an optional title
POST /approvals/{id}/approvegate's approver rolesApprove
POST /approvals/{id}/rejectgate's approver rolesReject with a reason
•
A gate's 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.
•
You cannot approve content you submitted: 403 self_approval.
•
One approval per person. Approving twice returns 409 already_approved. requiredApprovers counts distinct people.
•
Once an approval is 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.
•
A gate with pending approvals cannot be deleted: 409 gate_in_use with details.pending. Switch it off with enabled: false instead, or decide the approvals first.

Scheduled Publishing

EndpointRoleDescription
GET /schedulesmemberList schedules in every status. ?status= filters
POST /schedulesmemberSchedule content to go live at a future time
PATCH /schedules/{scheduleId}creator or adminChange the time, content or commit message
DELETE /schedules/{scheduleId}creator or adminCancel 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.

Note

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.

EndpointRoleDescription
GET /previewsmemberList previews
POST /previewsmemberCreate a preview record
PATCH /previews/{previewId}memberSet a preview's status

Style Rules & Linter

EndpointRoleDescription
GET /lintermemberGet linter configuration
PUT /linteradminUpdate linter configuration
GET /style-rulesmemberList custom style rules
POST /style-rulesadminAdd a rule (terminology, tone, banned phrases)
PATCH /style-rules/{ruleId} · DELETE /style-rules/{ruleId}adminUpdate / remove
POST /lintmemberLint one page's content on demand
POST /lint-runsadminLint every page in the repository
GET /lint-runs/latestmemberThe newest completed project-wide run and its counts
GET /lint-resultsmemberLatest lint results
POST /lint/auto-fixadminApply 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

EndpointRoleDescription
GET /glossarymemberList terms, alphabetically, with meta.total
POST /glossaryadminAdd a term, with an optional definition
POST /glossary/importadminImport terms from CSV
PATCH /glossary/{termId} · DELETE /glossary/{termId}adminUpdate / 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

EndpointRoleDescription
GET /ownershipmemberPage → owner assignments, each with lastChangedAt
POST /ownershipadminAssign an owner to a path pattern
GET /ownership/stalememberOwned pages that have gone stale
GET /ownership/summarymemberCoverage, stale count, unowned pages and alert settings
PATCH /ownership/settingsadminStale 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

EndpointRoleDescription
GET /access-rules · POST /access-rulesadminPath-based access rules
PATCH /access-rules/{ruleId} · DELETE /access-rules/{ruleId}adminUpdate / remove
GET /ip-allowlists · POST /ip-allowlistsadminIP allowlists for gated docs
PATCH /ip-allowlists/{listId} · DELETE /ip-allowlists/{listId}adminUpdate / remove
POST /access-checkmemberTest whether a visitor would have access
GET /access-logsadminAccess audit log

Access rules, IP allowlists and access logs are admin-only even to read.

Warning

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.

Warning

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.
•
On 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".

•
Trimmed, then 1–64 characters. A longer (or blank) value returns 400.
•
Free text, not an enum — the label is stored and returned exactly as sent.
•
Send null on PATCH to clear it. Omitting it leaves the stored value unchanged.
•
The doc site does not act on it yet: it is a label for your own tooling and the dashboard, and does not change what readers see.

Access log entries

Each entry from GET /access-logs (newest first; optional pagePath and limit query parameters, default limit 100) includes:

FieldTypeDescription
whostring | nullThe 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
audienceProfileIdstring | nullThe audience profile whose access token was presented, if any

Alongside id, projectId, pagePath, userId, visitorId, accessMethod, ipAddress, granted, deniedReason and createdAt.

Note

Doc-site page views are not written to the access log yet, so GET /access-logs currently returns an empty list.

Note

For audience-based content gating (partner tiers, logged-in users), see Audiences and the Audience Gating guide.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext