Public API

The CI/CD Watch REST API lets you access your pipeline data programmatically. Build custom dashboards, integrate with internal tools, or automate reporting.

Authentication

API requests are authenticated with API keys. Create one from Settings > API Keys.

Creating a key: Give the key a name (e.g. “MCP Server” or “Dashboard Script”), choose a scope (read or read-write), and optionally set an expiry date. The full key is shown once at creation, copy it immediately.
Using the key: Pass the key in the Authorization header:

curl -H "Authorization: Bearer cw_your_key_here" \
  https://api.cicd.watch/v1/runs

Keys are scoped to your organisation. All data returned is limited to repositories your team has connected.

Rate Limiting

API key requests are rate-limited to 60 requests per minute per key. When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Response Format

All responses are JSON. Successful responses wrap data in a data envelope. Error responses use an error envelope with code and message fields.

// Success
{ "data": [ ... ] }

// Error
{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } }

Endpoints

All endpoints are under api.cicd.watch/v1.

Runs

Method	Endpoint	Description
GET	/runs	List pipeline runs with optional filters
GET	/runs/:id	Get a single run with job details

Inventory

Method	Endpoint	Description
GET	/connections	List CI/CD provider connections
GET	/repos	List tracked repositories

Metrics

Method	Endpoint	Description
GET	/metrics/dora	DORA metrics for a given period
GET	/metrics/costs	Cost breakdown and waste analysis
GET	/metrics/performance	Pipeline performance analysis

Audit

Method	Endpoint	Description
GET	/audit/runs	List audit runs in reverse chronological order with status, timing, and worker info
GET	/audit/runs/:id	Get a single audit run by ID with lifecycle timestamps
GET	/audit/findings	List audit findings with optional state, pillar, rule, org, and repo filters. Free tier returns counts only; paid tiers return full evidence

See the Audit docs for the underlying concepts (pillars, severity tiers, finding shapes).

API key management

Method	Endpoint	Description
GET	/api-keys	List API keys for the tenant. The key value itself is never returned, only metadata (name, scope, last used, expiry)
POST	/api-keys	Create a new API key. The full key is returned only in this response. Requires read-write scope on the calling key
DELETE	/api-keys/:id	Revoke an API key. Subsequent requests using the revoked key fail with 401

See Settings, API Keys for the UI flow.

Common Parameters

Most endpoints accept query parameters for filtering:

periodDays: Number of days to look back (1–365). Used by metrics and run listing endpoints.
provider, org, repo: Filter metrics by provider, organisation, or repository.