API access

Everything you can do in the CCD dashboard, you can do over HTTP. Your whole workspace (agent tasks, fleet, projects, billing data) is scriptable.

Your API keys

Issue your own keys from the Developer portal. Give each key a name (for example "CI deploy" or "prod backend"), pick its access level, and copy the secret. A key looks like:

ccd_live_2a749b1c4e...

The full secret is shown once, at creation. We store only a peppered hash, so a stolen database yields no usable keys, and nobody, including us, can recover a secret later. Lost a key? Rotate it (issues a fresh secret, kills the old one) or revoke it, right from the portal. You can hold as many named keys as you need and retire them independently, so rotating one integration never disturbs another.

Two access levels:

• Read and write: full programmatic access (the default).
• Read only: GET/HEAD requests only. A write attempt returns 403. Good for dashboards, exports, and monitoring.

When you create a key you can also, optionally:

• Set an expiry (30 days, 90 days, a year). The key stops working automatically on that date.
• Lock it to source IPs: a comma-separated list of addresses or CIDR ranges (for example 203.0.113.4, 10.0.0.0/24). Requests from anywhere else are refused, even with the right secret.

Authenticate any request by sending the key in the X-API-Key header, or as a standard Bearer token. The Bearer form drops straight into most AI tools, HTTP clients, and generated SDKs:

# these two are equivalent
curl -H "X-API-Key: $CCD_API_KEY"        https://your-ccd-host/api/fleet/status
curl -H "Authorization: Bearer $CCD_API_KEY" https://your-ccd-host/api/fleet/status

No OAuth dance, no token refresh. Browser sessions use a login cookie instead, and all forms are accepted.

Not sure a key works? Ask the platform who you are:

curl -H "Authorization: Bearer $CCD_API_KEY" https://your-ccd-host/api/developer/whoami
# -> { "company_id", "scopes", "plan", "usage": {...}, "rate_limit_per_minute" }

Treat a key like a password: it carries your company's access. Do not commit it to repositories. The agent's own log redaction scrubs keys it sees, but the key itself grants access. If one leaks, revoke it in the portal. Every create, rotate, revoke and blocked attempt is written to a security log you can read at GET /api/developer/audit or on the Developer page.

The original company key from your welcome email still works, as a legacy read-and-write key. Named keys are the better path: they are scoped, individually revocable, can expire, can be IP-locked, and show you when each was last used.

What an API key cannot do

Keys are built so that a leaked one cannot escalate into account takeover. Regardless of a key's access level, these stay session-only (a logged-in human in the dashboard):

• Creating, rotating, or revoking API keys
• Reading or writing app secrets
• The platform admin surface

And unless a key is explicitly admin-scoped, it can read but not change company settings, tenancy, billing, credits, or move money. Two more automatic guards run on every request: a source that keeps presenting invalid keys is temporarily blocked, and oversized request bodies are refused before any handler sees them.

Example: start an agent task from a script

curl -X POST \
  -H "X-API-Key: $CCD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Run the test suite for ~/projects/shop and summarize failures"}' \
  "https://your-ccd-host/api/agent/quick-start"

This creates a project and agent session (auto-routed to your best online node) and returns the new session_id. Open /agent?session=<sid> to watch it live, or keep polling the session over the API.

The full API reference

CCD documents its own API live, generated from the running platform, so it is never out of date:

• /api-docs: browsable, searchable reference of every endpoint (requires login) with methods, path parameters, auth requirements, and copyable curl examples
• /api/reference/openapi.json: OpenAPI 3.0 spec you can import straight into Postman or Insomnia
• /api/reference.md: the whole reference as markdown, handy for feeding to your own AI tools

Errors

Every /api/* endpoint returns JSON errors with a consistent shape:

{ "error": "Invalid API key" }

Rate limits and quotas

Two limits apply to X-API-Key traffic, both by plan. Browser dashboard usage never counts against either.

• Per minute: a burst limit (60/min on Starter, 300 on Team, 1,200 on Scale, uncapped on Enterprise). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the window frees up). Over the limit returns 429 with a Retry-After in seconds.
• Per month: a total allowance (10,000 on Starter, 100,000 on Team, 500,000 on Scale, unlimited on Enterprise). See Billing & plans. Over the allowance returns 429; upgrade your plan or buy an API add-on to raise it.

Check your consumption any time:

curl -H "X-API-Key: $CCD_API_KEY" https://your-ccd-host/api/usage/api-calls

{
  "plan": "team",
  "month": "2026-07",
  "used": 1284,
  "limit": 100000,
  "remaining": 98716,
  "unlimited": false,
  "rate_limit_per_minute": 300
}

Bring your own AI keys (BYOK)

You can attach your own AI provider keys so agent runs bill against your provider account instead of platform quota:

• Managed from the API Keys manager on the Agent page
• DeepSeek and Groq keys are actively routed to today; keys for other major providers (OpenAI, Anthropic, Google, Mistral, and more) can be stored and tested, ready for when routing lands
• Keys are encrypted at rest on the platform
• Priority is your key first: a funded DeepSeek key of your own keeps runs alive even when platform capacity is constrained

Note the distinction: your CCD API key authenticates you to CCD; BYOK provider keys are what the agent uses to think.