API

Everything the app does goes through the same JSON API, so anything you can do in Trailboss you can script.

Authentication

Create a token in Settings → API tokens. Choose its scopes (workspace:read, work:write, approvals:decide, policy:manage, risk:accept, settings:manage) and when it expires. The token is shown once; send it on every request:

curl https://app.trailboss.dev/api/issues -H "Authorization: Bearer tbk_…"

A personal token acts for you; an organization token acts for the workspace, and admins manage it. Either way it can do no more than its scopes allow. Actions that need a second factor, like approving a risky change, can't be done with a token.

Requests and responses

Bodies are JSON. Every response carries an x-request-id header; quote it when you contact us.

Errors have one shape:

{ "error": { "code": "validation_error", "message": "Request validation failed", "details": [] } }
Status Meaning
400 The request is malformed or fails validation (details says where).
401 No valid token or session.
403 Your role or the token's scopes don't allow it.
404 Not found, or not in your workspace.
409 Conflicts with the current state (try again after reading it).
429 Rate limited: wait Retry-After seconds.
500 Our fault; the message carries a reference to quote.

Retrying safely

Send an Idempotency-Key header (any unique string, up to 255 characters) with a POST. A retry with the same key gets the first response back, marked idempotent-replayed: true, and nothing runs twice. Keys are kept for 24 hours.

Lists

Lists return a page at a time: ?limit= (up to 200) and ?cursor= with the nextCursor of the previous page. nextCursor is null on the last page.

Rate limits

Limits are per workspace (reads, writes, and a smaller budget for expensive calls like knowledge search and planning), and per address for sign-in and failed authentication. Past a limit you get 429 with Retry-After.

The event stream

GET /api/v1/events?topics=issue,release streams changes as Server-Sent Events. Topics: issue, project, release, preview, job, usage, approval, audit. Add subjects= (ids) to follow particular items.

Each event's id is its position in the stream: reconnect with Last-Event-ID and you get everything after it. If you were away longer than the 24 hours kept, a reset event tells you to read the current state again. A heartbeat arrives every 15 seconds.

Endpoints

Method and path What it does
GET /api/issues Issues, newest first; ?status= to filter.
POST /api/issues Create an issue: title, and optionally description, status, priority, assigneeId, projectId, labels.
GET /api/issues/{id} One issue with its history.
GET /api/projects Projects and where they stand.
GET /api/releases Releases and their stages.
GET /api/approvals Approvals and their state.
GET /api/audit The audit log; ?q=, ?action=, ?actor= to search.
POST /api/knowledge/search What a question retrieves from your knowledge sources: { "query": "…" }.
GET /api/org/export Everything the workspace holds, as one file (owners).
GET /api/health Whether the service answers. No token needed.

The app uses more endpoints than these; the ones listed here are kept stable.