Get started
Authentication
Every interface — REST, MCP, and OAuth — resolves to the same authorization model. Requests authenticate with an API key or a signed-in session, and are checked against explicit scopes.
API keys
Send Authorization: Bearer dsk_…. Workspace-scoped, hashed at rest, shown once.
Session
Signed-in browser sessions authenticate automatically and resolve to your capabilities.
How API keys work
Create and manage keys from API Keys. Here's the full lifecycle, exactly as implemented today.
Authorization: Bearer dsk_live_••••••••••••••••Store keys securely
Scopes
API keys carry explicit scopes. A request with an insufficient scope returns 403 scope_insufficient. Grant the minimum a key needs. Scopes marked write can modify data.
Scopes are capability gates, not resource visibility grants
Documents & content
documents:readList and retrieve documents, packages, versions, and metadata.
readdocuments:writeCreate, update, and delete documents and their metadata.
writecontent:readRead raw document content blocks and structured content trees.
readcontent:writeReserved: modify document content blocks and structured content trees. No public operation is gated by this scope yet; it is not grantable until a content-write API ships.
writeassets:readReserved: list and download document assets. No public operation is gated by this scope yet; it is not grantable until an assets API ships.
readassets:writeReserved: upload, replace, and delete document assets. No public operation is gated by this scope yet; it is not grantable until an assets API ships.
writecomments:readList and read comment threads and suggestions.
readcomments:writeCreate, edit, and resolve comment threads and suggestions.
writesearch:readSearch documents, content, and metadata across the workspace.
readanalytics:readAccess document engagement and usage analytics.
readWorkflow
workflow:readRead document workflow state, available transitions, and approval history.
readworkflow:writeTrigger workflow transitions and submit approvals.
writeExports
exports:readExport documents to PDF, DOCX, and Markdown formats.
readProjects
projects:readRead project and engagement identity, lifecycle state, membership, and settings without financial details.
readprojects:writeCreate, update, archive, and manage project/engagement identity, membership, and settings through confirmed commands.
writeengagements:readCustomer and commercial-engagement identity, hierarchy, status, and engagement-project links (read-only). No financials, rates, or contract terms.
readproject-health:writeAcknowledge advisory Project Health alerts through confirmed, idempotent commands.
writefinancials:readRead project financial health: budget, margin, burn rate, and forecasts. Equivalent to the revops:view_margin session permission.
readstaffing:readRead project staffing status: role coverage, discipline gaps, open requests, and delivery risk signals. Equivalent to the revops:view_capacity session permission.
readagent:readRead agent-optimized project delivery, sprint, and risk read models via the Agent API (/api/agent/v1). Directional signals only — no rates, invoice data, or personal metadata.
readcontext-engine:readSearch and inspect governed context packages, evidence references, provenance, freshness, coverage, and contributing providers.
readcontext-opportunity:writeRecord a Context Opportunity — an evidence-backed, advisory proposal that some governed domain may warrant an action. Never approves, mutates, or promotes governed truth; creates ONLY an opportunity record.
writedelivery-timeline:readRead governed delivery milestones, workstreams, and timeline geometry without moving execution coordinates.
readdelivery-timeline:writeRun explicit milestone status, target-date, and progress commands through the governed Delivery command path.
writeestimates:readRead project-scoped estimates, effort, role demand, scope, immutable versions, and comparisons.
readestimates:writeCreate estimates, update bounded draft metadata, and persist reviewable estimate change proposals.
writeestimates:operateRequest human baseline review or explicitly freeze an immutable estimate baseline.
writeWork items
sprints:readRead sprint planning context, readiness, reports, and proposal-only planning suggestions. Does not apply plans or move work.
readwork-items:readList and retrieve canonical Execute work items, transition history, and read-only board projections.
readwork-items:commentCreate and edit authorized work-item comments, including provider writeback when the source owns comments.
writework-items:transitionApply valid Execute or provider-backed workflow transitions with audit history.
writework-items:assignAssign, reassign, or unassign eligible owners without granting staffing or capacity authority.
writework-items:scheduleSet or clear governed date and sprint placement fields through the Execute command boundary.
writework-items:estimateSet or clear points/estimate fields without exposing commercial rates, margins, or subscription data.
writework-items:linkManage labels and normalized work-item relationships such as dependencies, related, duplicates, and parent/child links.
writework-items:blockersRaise, update, transition, and resolve blockers linked to work items.
writework-items:focusPin, annotate, reprioritize, snooze, or clear work items in governed focus views.
writework-items:bulkRun bounded, confirmation-required bulk operations across authorized work items.
writework-item-enhance:readRead Work Item Enhance runs, generated drafts, artifacts, evidence references, and apply history.
readwork-item-enhance:runCreate proposal-first Work Item Enhance runs and execute bounded enhancement actions.
writework-item-enhance:applyApply selected Work Item Enhance drafts back to authorized canonical work-item fields.
writework-item-enhance:code-contextInspect authorized repository/code context for Work Item Enhance implementation planning without writing code.
readRevenue operations
opportunities:readList and retrieve revenue opportunities and delivery forecasts.
readAudit
audit:readRead the account-level audit event stream. Requires an Enterprise plan and the audit:account.view session permission. Equivalent to viewing the account audit dashboard.
readWebhooks
webhooks:manageCreate, update, delete, and inspect webhook registrations.
writeTime management
time:read_selfRead the authenticated user's time entries and time-management state.
readtime:write_selfCreate and change explicit time entries for the authenticated user. Inferred time remains proposal-only.
writetime:submit_selfSubmit or recall the authenticated user's reviewed work day. Never grants approval authority.
writetime:read_teamRead only time submissions the authenticated user is eligible to review in the active workspace.
readtime:approve_teamApprove or reject time submissions where the authenticated user is an eligible approver.
writetime:importStart provider-backed time import runs for the authenticated user with immutable source identity.
writetime:reconcileRead and resolve authorized provider reconciliation findings without changing provider authority.
writeAdmin
adminWildcard over every scope-gated operation — equivalent to holding every scope. Deliberately does NOT satisfy capability-gated routes (financial health, staffing status, audit log, delivery forecast): those require session authentication regardless of key scopes. Use with care.
writeRate limits
Limits are applied per API key — and, identically, per workspace and delegated-OAuth principal for OAuth-authenticated requests (REST, GraphQL, and MCP all share the same underlying check, so none of them get more headroom than an API key would). Every response includes these headers; a 429 rate_limit_exceeded is returned when exceeded.
X-RateLimit-LimitTotal requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (only on 429)
Errors
Errors share a consistent JSON envelope with a stable code, a human-readable message, and the HTTP status.
missing_authNo API key or session was provided.
Fix: Add an Authorization: Bearer <key> header.
invalid_api_keyThe key is malformed, unknown, or revoked.
Fix: Check the key value, or create a new one in API Keys.
api_key_expiredThe key is past its expiry date.
Fix: Create a new key and update your integration.
scope_insufficientThe key lacks the scope the endpoint requires.
Fix: Grant the required scope (shown on each endpoint) to a key.
bad_requestA required field is missing or has the wrong type.
Fix: Check the request body against the endpoint reference.
not_foundThe resource does not exist or is outside your workspace.
Fix: Verify the id and that it belongs to your workspace.
rate_limit_exceededToo many requests in the current window.
Fix: Honor the Retry-After header and back off exponentially.
internal_errorAn unexpected error occurred on our side.
Fix: Retry with backoff; contact support if it persists.
Each endpoint in the API reference also lists the specific errors it can return.