API Tokens & REST API
Colony Cloud exposes a REST API surface authenticated with a connection — a delegation bounded by your grants that survives token rotation. Use it to integrate Colony pipeline data into your own tooling, scripts, or CLI workflows without going through the MCP server.
1. Connections
Section titled “1. Connections”A connection is an OAuth 2.1 delegation (mcp_at_… access token) issued to a client acting on your behalf. It carries your grants, so it can only do what you’re allowed to do, and it survives rotation — the short-lived access token refreshes silently without you having to reissue a credential by hand.
Rotation
Section titled “Rotation”Access tokens are short-lived and rotate automatically via a refresh token — there is no manual “rotate” step for well-behaved clients. If a connection is compromised, revoking it invalidates both the access and refresh token immediately.
Treat any credential derived from a connection like a password. Anyone who holds it can read your org’s pipeline data within the scope of its grants.
2. Authentication
Section titled “2. Authentication”Include the token in the Authorization header of every request:
Authorization: Bearer mcp_at_YOUR_TOKENAll token-authenticated endpoints are under https://app.runcolony.com. There is no separate API base URL — the dashboard and API share the same domain.
Example with curl:
curl -s \ -H "Authorization: Bearer mcp_at_YOUR_TOKEN" \ "https://app.runcolony.com/api/cli/bootstrap"A missing or invalid token returns 401 Unauthorized. An expired token also returns 401.
3. CLI Endpoints
Section titled “3. CLI Endpoints”The following endpoints are authenticated with a connection. All accept owner/name format for the repo parameter (e.g. acme/my-repo).
| Method | Path | ?repo | Description |
|---|---|---|---|
GET | /api/cli/bootstrap | Optional | Return org metadata, enabled repos, and the pipeline store mode and minimum version. |
GET | /api/cli/issues | Required | List pipeline issues for a repo, optionally filtered by state. |
GET | /api/cli/issues/{number}/why | Required | Return current state, recent transition history, and last error for a specific issue. |
GET | /api/cli/pipeline/overview | Required | Return a full pipeline health snapshot — open issues, queue depth, Workers, costs. |
GET /api/cli/bootstrap
Section titled “GET /api/cli/bootstrap”Returns org details, the list of enabled repos, and the pipeline store mode and minimum version for the authenticated org. The repo list is paginated with limit and offset; the default page holds up to 1,000 repos, so a client that ignores pagination still sees every enabled repo of a typical org. Repos with no matching Pipeline Store tenant are omitted and are not counted in pagination.total.
| Parameter | In | Required | Description |
|---|---|---|---|
repo | query | No | Filter to a single repo in owner/name format. Returns 404 if the repo is not enabled in this org. |
limit | query | No | Page size. Default 1000, maximum 1000. |
offset | query | No | Number of repos to skip. Default 0. |
The response carries org, repos, pipelineStore and cloudUrl, plus a pagination object:
{ "pagination": { "limit": 1000, "offset": 0, "total": 42, "hasMore": false } }Repos are ordered by lower-cased owner, then lower-cased name. With ?repo=, pagination.total is 1.
# All repos in the orgcurl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/bootstrap"
# Scoped to one repocurl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/bootstrap?repo=acme/my-repo"GET /api/cli/issues
Section titled “GET /api/cli/issues”Lists pipeline issues for a repo. Returns all non-done issues by default.
| Parameter | In | Required | Description |
|---|---|---|---|
repo | query | Yes | Repository in owner/name format. |
state | query | No | Filter by state. See accepted values below. |
Accepted state values:
| Value | Issues returned |
|---|---|
open (default) | All issues where state != 'done' |
blocked | Issues where is_blocked = true and state != 'done' |
paused | Issues where is_paused = true and state != 'done' |
| Any pipeline state string | Issues in exactly that state (e.g. in-review, analyzing, failure-blocked) |
# Open issues (default)curl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/issues?repo=acme/my-repo"
# Blocked issues onlycurl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/issues?repo=acme/my-repo&state=blocked"
# Issues in a specific pipeline statecurl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/issues?repo=acme/my-repo&state=in-review"GET /api/cli/issues/{number}/why
Section titled “GET /api/cli/issues/{number}/why”Returns the current state, a summary of recent state transitions, and the last agent error for a specific issue number.
| Parameter | In | Required | Description |
|---|---|---|---|
number | path | Yes | Positive integer issue number. |
repo | query | Yes | Repository in owner/name format. |
curl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/issues/42/why?repo=acme/my-repo"GET /api/cli/pipeline/overview
Section titled “GET /api/cli/pipeline/overview”Returns a comprehensive pipeline health snapshot for a repo, including all open issues, queue depth by task type, in-flight tasks, Worker pool status, blocked issues, recent agent failures, and LLM cost over four windows (24 h, 7 d, 30 d, all time).
| Parameter | In | Required | Description |
|---|---|---|---|
repo | query | Yes | Repository in owner/name format. |
curl -H "Authorization: Bearer mcp_at_…" \ "https://app.runcolony.com/api/cli/pipeline/overview?repo=acme/my-repo"4. Accepting work
Section titled “4. Accepting work”Session-authenticated dashboard routes run operator actions on a pipeline item.
POST /api/pipeline/issues/{owner}/{repo}/{number}/operator-action
Section titled “POST /api/pipeline/issues/{owner}/{repo}/{number}/operator-action”Runs an operator action. Accept is the approve intent. On an epic in human-review-ready it accepts the open blocking findings and merges the epic branch with its children once checks pass, with no code-host review needed. Your role needs the same grant as Accept on a normal item; otherwise the API returns 403.
Request fields for an Accept:
| Field | Type | Description |
|---|---|---|
expectedHeadSha | string | The head commit you reviewed. A moved head is refused with HEAD_MOVED. |
followup | followup or no-followup | Polish-finding follow-up. Omit to use the repository default. Applies only to Accept. |
note | string | Optional note, at most 2,000 characters. Applies only to Accept. |
When Colony hasn’t confirmed the Accept yet, the response carries outcome: "pending"; the item’s progress shows the rest. Refusals accept nothing and return 409 with the pipeline’s message:
| Code | Meaning |
|---|---|
HEAD_MOVED | The head commit moved after you reviewed it. |
WRONG_STATE | The item is not in a state that allows Accept. |
ITEM_PAUSED | The item is paused. |
ALREADY_DECIDED | The escalation was already decided. |
NOTHING_TO_ACCEPT | There are no blocking findings to accept. |
EPIC_SUBTASK | The item is a subtask; accept its epic instead. |
NOT_EPIC | An epic-only action was sent for an item that is not an epic. |
CODE_HOST_UNAVAILABLE | The code host couldn’t be reached or didn’t allow the action. |
The acceptance is recorded in the audit log as review.approved, with the head, the accepting actor, the accepted finding ids, the follow-up choice, whether a note was given (never its text) and the outcome.
The epic field on item detail
Section titled “The epic field on item detail”GET /api/pipeline/issues/{owner}/{repo}/{number} returns epic, which is null for an item outside any epic.
- For an epic:
role: "epic",branch,baseBranch,childCount(subtask edges of any status),escalation,blockingFindings(id, title, summary, severity, recommendation),escalationReasons, andacceptProgress(phase,actor,acceptedAt,reason, andbyViewer, true whenactoris the caller). acceptProgressisnulluntil an acceptance is recorded. Then it holdsphase(waiting-on-checks,merging,mergedornot-merged),actor,acceptedAtand, fornot-merged,reason.- For a subtask:
role: "subtask",branchandepicNumber.
5. Machine-Readable OpenAPI Spec
Section titled “5. Machine-Readable OpenAPI Spec”A machine-readable OpenAPI 3.1 document covering the Colony Cloud Service API is available at:
https://app.runcolony.com/api/openapi.jsonYou can use this spec to generate typed clients, import routes into API testing tools, or explore request and response schemas. Most of its operations take a dashboard session rather than a connection: only /api/cli/* and /mcp accept a connection token.
curl -s https://app.runcolony.com/api/openapi.json | jq '.paths | keys'See /cloud/api-reference/ for a human-readable table of its verbs, paths, summaries, and request and response schemas.
Troubleshooting
Section titled “Troubleshooting”401 Unauthorized
Section titled “401 Unauthorized”The token is missing, malformed, or expired.
- Confirm the
Authorizationheader value is exactlyBearer mcp_at_YOUR_TOKENwith no extra whitespace. - Confirm the token starts with
mcp_at_— Worker tokens use a different prefix and are not accepted here. - If the access token has expired, a compliant client refreshes it automatically; otherwise reconnect to obtain a fresh connection.
404 Repository Not Found
Section titled “404 Repository Not Found”The ?repo value does not match a repo that is enabled in your org or accessible to this token.
- Confirm the repo is enabled in Colony Cloud under Account → Tenants → your tenant → Repositories (
/account/tenants/:tenantId/repositories) or the per-repo enable flow. - Confirm the
owner/nameformat is correct and case matches (the API normalizes to lowercase internally, but a missing slash returns a 400 instead).
400 Invalid repo format
Section titled “400 Invalid repo format”The ?repo parameter was provided but does not contain a / separating owner and name.
- Use
owner/nameformat — e.g.acme/my-repo, notacmeormy-repo.