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

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.

Note

There is currently no self-serve dashboard page for minting a connection by hand — that surface is being built (tracked separately). The colony auth login CLI flow obtains a connection automatically; if you’re integrating a custom script or tool today, reach out rather than looking for a token-generation page under Settings.

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

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:

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

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 pipeline store connection info.
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

Returns org details, the list of enabled repos, and pipeline store connection information for the authenticated org.

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.

# 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"

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 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"

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

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. Machine-Readable OpenAPI Spec

A full machine-readable OpenAPI 3.1 document covering all Colony Cloud API endpoints 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 the full request and response schemas for every endpoint — including the Worker and MCP endpoints not listed above.

curl -s https://app.runcolony.com/api/openapi.json | jq '.paths | keys'

See the full endpoint reference at /cloud/api-reference/ for a human-readable table of every verb, path, summary, and request/response schema.

Troubleshooting

401 Unauthorized

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.

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 Settings → Repos & access 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).

400 Invalid repo format

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.