REST API

Base URL

https://api.cospec.io/v1

Authentication

All requests require a Bearer token (your API key).

Terminal

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

See API Keys for key management.

Request Format

JSON request and response bodies
Content-Type: application/json
All timestamps in ISO 8601 (UTC)

Core Resources

Resource	Description	Endpoint prefix
Runs	Agent execution sessions	`/v1/runs`
Templates	Reusable sandbox configurations	`/v1/templates`
Usage	Credits and billing	`/v1/usage`

Create a Run

Terminal

curl -X POST https://api.cospec.io/v1/runs \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-org/your-repo",
    "prompt": "Refactor the auth middleware to use JWT",
    "template": "your-template",
    "model": "sonnet"
  }'

Additional fields like branch, guardrails (maxTurns, maxCostUsd, timeoutSeconds), env, and metadata are available. See the Create Run API reference for the full schema.

Response:

{
  "id": "run_abc123",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00Z"
}

Check Run Status

Terminal

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

Runs follow this lifecycle:

pending → running → completed | failed | cancelled

See Runs for full lifecycle details.

Get Results

Polling

Poll GET /v1/runs/:id every 5-10 seconds until the run reaches a terminal status.

Webhooks

Terminal

curl -X POST https://api.cospec.io/v1/webhooks \
  -H "Authorization: Bearer csk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/cospec",
    "events": ["run.completed", "run.failed", "run.cancelled"]
  }'

When a run reaches a terminal state, coSPEC sends a POST to your URL:

{
  "event": "run.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "run": {
    "id": "run_abc123",
    "status": "completed",
    "outputs": [...],
    "usage": { "totalCostUsd": 0.42 }
  }
}

Events: run.completed, run.failed, run.cancelled.

See the Webhooks API reference for full details.

Output Fields

Outputs are detected automatically based on what the agent does during the run. Each output has a type plus type-specific fields.

Type	Fields
`pr`	`url`, `title`, `number`
`branch`	`name`, `remote`
`issue`	`url`, `title`, `number`
`text`	`content`

A text output is always present for completed runs — it contains the agent's summary of what it did.

Example completed run (trimmed):

{
  "id": "run_abc123",
  "status": "completed",
  "outputs": [
    {
      "type": "text",
      "content": "Refactored the auth middleware to use JWT tokens instead of session cookies."
    },
    {
      "type": "pr",
      "url": "https://github.com/your-org/your-repo/pull/42",
      "title": "Refactor auth middleware to use JWT",
      "number": 42
    },
    {
      "type": "branch",
      "name": "cospec/refactor-auth-jwt"
    }
  ],
  "usage": {
    "totalCostUsd": 0.42
  }
}

Errors

Errors follow RFC 9457 (Problem Details). Every error response includes:

{
  "type": "RUN_NOT_FOUND",
  "title": "Run not found",
  "status": 404,
  "detail": "No run exists with the given ID",
  "requestId": "req_abc123"
}

Field	Description
`type`	Machine-readable error code
`title`	Human-readable message
`status`	HTTP status code
`detail`	Optional extra context
`requestId`	For log correlation and support
`errors`	Per-field validation errors (when applicable)

Common Error Codes

Category	Codes
Auth	`AUTH_UNAUTHORIZED`, `AUTH_FORBIDDEN`, `API_KEY_INVALID`
Runs	`RUN_NOT_FOUND`, `RUN_API_KEY_REQUIRED`, `RUN_GITHUB_APP_NOT_INSTALLED`
Templates	`TEMPLATE_NOT_FOUND`, `TEMPLATE_SLUG_EXISTS`, `TEMPLATE_SYSTEM_READONLY`
Usage	`USAGE_INSUFFICIENT_CREDITS`
Validation	`VALIDATION_FAILED` (includes per-field `errors` array)

For complete endpoint schemas, request/response types, and the full error code reference, see the API Reference.

What's Next

API Reference — full endpoint schemas and response types
Templates — reusable sandbox configurations
Zapier, Make, n8n — platform-specific guides

On this page