API Tokens & REST API

Colony Cloud exposes a REST API surface authenticated with cct_ API tokens. Use it to integrate Colony pipeline data into your own tooling, scripts, or CLI workflows without going through the MCP server.

1. API Tokens

Create a token

1. Sign in and go to Settings → Organization → Integrations.
2. Click New Token.
3. Give the token a descriptive name (e.g. my-cli-script or ci-pipeline).
4. Click Create — copy the token value (cct_…) immediately; it is shown only once.
5. Optionally set an expiry date. Tokens without an expiry remain valid until manually revoked.

Caution

The token value is shown only at creation time. Colony does not store it in recoverable form. If you lose it, revoke the token and create a new one.

Token properties

Property	Detail
Prefix	cct_ followed by a UUID
Scope	Organization-scoped — grants access to all repos in your org that are enabled in Colony Cloud
Expiry	Optional expires_at date. Expired tokens return 401.
Rotation	Revoke the old token from Settings → Organization → Integrations and create a new one. Update all consumers before revoking.

Treat tokens like passwords. Anyone who holds a token can read your org’s pipeline data.

Rotate a token

1. Go to Settings → Organization → Integrations.
2. Create a new token and update all consumers with the new value.
3. Revoke the old token by clicking Delete next to it.

2. Authentication

Include the token in the Authorization header of every request:

Authorization: Bearer cct_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 cct_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 cct_ tokens. 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 cct_…" \
  "https://app.runcolony.com/api/cli/bootstrap"

# Scoped to one repo
curl -H "Authorization: Bearer cct_…" \
  "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 cct_…" \
  "https://app.runcolony.com/api/cli/issues?repo=acme/my-repo"

# Blocked issues only
curl -H "Authorization: Bearer cct_…" \
  "https://app.runcolony.com/api/cli/issues?repo=acme/my-repo&state=blocked"

# Issues in a specific pipeline state
curl -H "Authorization: Bearer cct_…" \
  "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 cct_…" \
  "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 cct_…" \
  "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'

Troubleshooting

401 Unauthorized

The token is missing, malformed, or expired.

• Confirm the Authorization header value is exactly Bearer cct_YOUR_TOKEN with no extra whitespace.
• Confirm the token starts with cct_ — Worker tokens and OAuth access tokens use different prefixes and are not accepted here.
• If the token has an expires_at date that has passed, generate a new one from Settings → Organization → Integrations.

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.