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.