API Overview

Base URL

All API requests go to:

https://api.cospec.io

Authentication

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

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 API Keys section.

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:

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

Error codes

Authentication

Runs

Templates

Webhooks

Repositories

Usage & credits

General

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 enforces 200 requests per minute per API key across all endpoints. Every response includes rate limit headers:

When the limit is exceeded, you'll receive a 429 response with error code RATE_LIMIT_EXCEEDED. Back off and retry after the Retry-After period.

If you're polling run status, we recommend intervals of 5–10 seconds to stay well within the limit.

Concurrent run limits

Each organization can have up to 10 concurrent runs (pending + running) at any time. If you try to create a run while at the limit, you'll receive a 429 response with error code CONCURRENT_RUN_LIMIT_EXCEEDED. Wait for existing runs to complete before starting new ones.