API Overview

The SidClaw API is a RESTful JSON API for governing AI agent operations. All endpoints are served under a versioned base path.

Base URL

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer sk_live_abc123...

API keys are scoped to a single tenant and carry a set of scopes that determine which endpoints the key can access. See Authentication for full details.

During local development with NODE_ENV=development, you can bypass authentication entirely with the X-Dev-Bypass: true header. This is not available in production.

Response Format

Success responses

Single-resource endpoints return the resource under a data key:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "deploy-agent",
    ...
  }
}

List endpoints include a pagination object alongside the data array:

{
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

The /evaluate endpoint returns a flat response object (no data wrapper) since it is the primary SDK integration point.

Error responses

All errors follow the ApiError shape:

{
  "error": "not_found",
  "message": "Agent not found: 550e8400-...",
  "status": 404,
  "details": {},
  "trace_id": "optional-trace-uuid",
  "request_id": "req-1234"
}

Pagination

List endpoints accept limit and offset query parameters.

The response includes a pagination object with total, limit, and offset fields so clients can compute page counts.

Rate Limiting

Requests are rate-limited per tenant, categorized by endpoint type. Limits are enforced over a 60-second sliding window.

Endpoint categories:

• Evaluate -- POST /evaluate
• Read -- all GET endpoints
• Write -- all POST, PATCH, PUT, DELETE endpoints (except evaluate)

Every response includes rate limit headers:

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for evaluate endpoints. Retry after 12 seconds.",
  "status": 429,
  "details": {
    "category": "evaluate",
    "limit": 100,
    "remaining": 0,
    "reset_at": 1711040520,
    "retry_after_seconds": 12
  },
  "request_id": "req-1234"
}

Common HTTP Status Codes

Content Type

All request and response bodies use application/json, except for CSV export endpoints which return text/csv.

Idempotency

The POST /evaluate endpoint is not idempotent -- each call creates a new audit trace. If you need to poll for an approval result, use GET /approvals/:id/status instead of re-evaluating.

Health Check

GET /health

Returns 200 OK with no authentication required. Use this for load balancer health probes.