API Overview

Base URL, versioning, pagination, and rate limiting for the Checkrd REST API.

API Overview

The Checkrd API is a REST API that uses JSON for request and response bodies. All endpoints are served over HTTPS at:

https://api.checkrd.io

Versioning

The API uses date-based versioning via the Checkrd-Version header. The current version is 2026-04-06. If omitted, the latest version is used.

bash

curl https://api.checkrd.io/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Checkrd-Version: 2026-04-06"

Authentication

Two authentication methods are supported depending on the endpoint:

Method	Header	Used by
JWT	`Authorization: Bearer <token>`	Dashboard users (all `/v1/` CRUD endpoints)
API Key	`Authorization: Bearer <api_key>`	SDKs and agents (telemetry, control signals)

JWTs are issued via WorkOS AuthKit login. API keys are created in the dashboard and have a ck_live_ or ck_test_ prefix.

See Authentication for details.

Pagination

List endpoints use cursor-based pagination. Pass limit (default 20, max 100) and an opaque cursor value from the previous response.

json

{
  "data": [...],
  "has_more": true,
  "next_cursor": "01916a3e-..."
}

To fetch the next page:

bash

curl "https://api.checkrd.io/v1/agents?limit=20&cursor=01916a3e-..."

Rate Limiting

Two tiers of rate limiting are enforced:

Per-IP: 20 requests/second (burst 40). Auth endpoints: 5 requests/second (burst 10).
Per-org: Telemetry ingestion is rate-limited by plan tier.

Rate limit headers are included on every response:

RateLimit-Limit: 20
RateLimit-Remaining: 18
RateLimit-Reset: 1712000000

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

Idempotency

All mutation endpoints (POST, PUT, DELETE) accept an Idempotency-Key header. Sending the same key within 24 hours returns the cached response without re-executing the operation.

bash

curl -X POST https://api.checkrd.io/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Idempotency-Key: unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{"name": "sales-agent"}'

Errors

All errors follow a consistent JSON format:

json

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "Name is required."
  }
}

See Errors for the full list of error types and codes.

Quickstart Authentication