API Overview

Base URL

All API requests go to:

https://api.cospec.io

Authentication

Authenticate every request with a Bearer token — your API key:

Terminal

curl https://api.cospec.io/v1/runs \
  -H "Authorization: Bearer csk_live_..."

API keys start with csk_live_ and are scoped to a single organization. Create and manage keys in the dashboard.

Request format

Content-Type: application/json for request bodies
Methods: GET for reads, POST for creates, PATCH for updates, DELETE for deletes

Errors

Error responses follow RFC 9457 (Problem Details for HTTP APIs):

{
  "type": "VALIDATION_FAILED",
  "title": "Validation failed",
  "status": 400,
  "detail": "Invalid request body",
  "instance": "/v1/runs",
  "requestId": "req-abc123"
}

Every error response includes:

Field	Type	Description
`type`	string	Machine-readable error code (e.g. `TEMPLATE_NOT_FOUND`)
`title`	string	Human-readable error summary
`status`	number	HTTP status code
`detail`	string?	Additional context about the error
`instance`	string?	Request path that caused the error
`requestId`	string?	Unique ID for support requests
`errors`	array?	Field-level validation errors (see below)

Validation errors

When type is VALIDATION_FAILED, the errors array contains per-field details:

{
  "type": "VALIDATION_FAILED",
  "title": "Validation failed",
  "status": 400,
  "errors": [
    {
      "field": "template",
      "message": "String must contain at least 1 character(s)",
      "code": "too_small"
    }
  ]
}

HTTP status codes

Status	Meaning
`400`	Bad request — invalid body, parameters, or state
`401`	Unauthorized — missing or invalid API key
`402`	Payment required — insufficient credits
`403`	Forbidden — action not allowed
`404`	Not found — resource doesn't exist
`409`	Conflict — duplicate resource or constraint violation
`429`	Too many requests — rate limit exceeded
`500`	Internal error — unexpected server failure
`502`	Bad gateway — upstream service failure
`503`	Service unavailable — sandbox failed to start

Error codes

Authentication

Code	Status	Message
`AUTH_UNAUTHORIZED`	401	Authentication required
`API_KEY_INVALID`	401	Invalid API key

Runs

Code	Status	Message
`RUN_TEMPLATE_NOT_FOUND`	400	Template not found
`RUN_API_KEY_REQUIRED`	400	Anthropic API key required. Configure in Settings
`RUN_GITHUB_APP_NOT_INSTALLED`	400	GitHub App not installed. Install in Settings
`RUN_ORCHESTRATOR_ERROR`	502	Failed to start run

Templates

Code	Status	Message
`TEMPLATE_NOT_FOUND`	404	Template not found
`TEMPLATE_SLUG_EXISTS`	409	A template with this slug already exists
`TEMPLATE_SYSTEM_READONLY`	403	System templates cannot be modified
`TEMPLATE_HAS_RUNNING_SANDBOXES`	409	Cannot delete template with running sandboxes

Usage & credits

Code	Status	Message
`USAGE_INSUFFICIENT_CREDITS`	402	Insufficient credits to perform this action

General

Code	Status	Message
`VALIDATION_FAILED`	400	Validation failed
`BAD_REQUEST`	400	Bad request
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`INTERNAL_ERROR`	500	An unexpected error occurred

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Control pagination with page and limit query parameters.

Rate limits

The API is rate-limited per API key. Current limits are generous for normal usage. If you hit a rate limit you'll receive a 429 Too Many Requests response — back off and retry.

On this page