Skip to content

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.

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.

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.

Include the token in the Authorization header of every request:

Authorization: Bearer mcp_at_YOUR_TOKEN

All 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:

Terminal window
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.

The following endpoints are authenticated with a connection. All accept owner/name format for the repo parameter (e.g. acme/my-repo).

MethodPath?repoDescription
GET/api/cli/bootstrapOptionalReturn org metadata, enabled repos, and the pipeline store mode and minimum version.
GET/api/cli/issuesRequiredList pipeline issues for a repo, optionally filtered by state.
GET/api/cli/issues/{number}/whyRequiredReturn current state, recent transition history, and last error for a specific issue.
GET/api/cli/pipeline/overviewRequiredReturn a full pipeline health snapshot — open issues, queue depth, Workers, costs.

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.

ParameterInRequiredDescription
repoqueryNoFilter to a single repo in owner/name format. Returns 404 if the repo is not enabled in this org.
limitqueryNoPage size. Default 1000, maximum 1000.
offsetqueryNoNumber 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.

Terminal window
# All repos in the org
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/bootstrap"
# Scoped to one repo
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/bootstrap?repo=acme/my-repo"

Lists pipeline issues for a repo. Returns all non-done issues by default.

ParameterInRequiredDescription
repoqueryYesRepository in owner/name format.
statequeryNoFilter by state. See accepted values below.

Accepted state values:

ValueIssues returned
open (default)All issues where state != 'done'
blockedIssues where is_blocked = true and state != 'done'
pausedIssues where is_paused = true and state != 'done'
Any pipeline state stringIssues in exactly that state (e.g. in-review, analyzing, failure-blocked)
Terminal window
# Open issues (default)
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/issues?repo=acme/my-repo"
# Blocked issues only
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/issues?repo=acme/my-repo&state=blocked"
# Issues in a specific pipeline state
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/issues?repo=acme/my-repo&state=in-review"

Returns the current state, a summary of recent state transitions, and the last agent error for a specific issue number.

ParameterInRequiredDescription
numberpathYesPositive integer issue number.
repoqueryYesRepository in owner/name format.
Terminal window
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/issues/42/why?repo=acme/my-repo"

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).

ParameterInRequiredDescription
repoqueryYesRepository in owner/name format.
Terminal window
curl -H "Authorization: Bearer mcp_at_…" \
"https://app.runcolony.com/api/cli/pipeline/overview?repo=acme/my-repo"

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:

FieldTypeDescription
expectedHeadShastringThe head commit you reviewed. A moved head is refused with HEAD_MOVED.
followupfollowup or no-followupPolish-finding follow-up. Omit to use the repository default. Applies only to Accept.
notestringOptional 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:

CodeMeaning
HEAD_MOVEDThe head commit moved after you reviewed it.
WRONG_STATEThe item is not in a state that allows Accept.
ITEM_PAUSEDThe item is paused.
ALREADY_DECIDEDThe escalation was already decided.
NOTHING_TO_ACCEPTThere are no blocking findings to accept.
EPIC_SUBTASKThe item is a subtask; accept its epic instead.
NOT_EPICAn epic-only action was sent for an item that is not an epic.
CODE_HOST_UNAVAILABLEThe 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.

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, and acceptProgress (phase, actor, acceptedAt, reason, and byViewer, true when actor is the caller).
  • acceptProgress is null until an acceptance is recorded. Then it holds phase (waiting-on-checks, merging, merged or not-merged), actor, acceptedAt and, for not-merged, reason.
  • For a subtask: role: "subtask", branch and epicNumber.

A machine-readable OpenAPI 3.1 document covering the Colony Cloud Service API is available at:

https://app.runcolony.com/api/openapi.json

You 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.

Terminal window
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.

The token is missing, malformed, or expired.

  • Confirm the Authorization header value is exactly Bearer mcp_at_YOUR_TOKEN with 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.

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/name format is correct and case matches (the API normalizes to lowercase internally, but a missing slash returns a 400 instead).

The ?repo parameter was provided but does not contain a / separating owner and name.

  • Use owner/name format — e.g. acme/my-repo, not acme or my-repo.