HTTP API reference

The DRC HTTP API is a versioned JSON API served by drc-orchestrator.

• Versioned routes use /api/v1.
• Health routes are unauthenticated.
• Product routes require a tenant-scoped API key or bearer JWT.
• Clients should branch on error.code, not the prose message.
• Responses include x-drc-api-version: v1 where applicable.
• The source OpenAPI document is docs/openapi.json.

Authentication

API key:

Authorization: ApiKey <key>

Bearer JWT:

Authorization: Bearer <token>

Create an account or log in through the account routes, or create a service API key in the authenticated web workspace. API key plaintext is returned only at creation; store it in a secret manager.

Health and metrics

Example:

curl -fsS https://api.example.com/health/ready

Executions

Create an execution:

curl -sS -X POST "$DRC_API_URL/api/v1/executions" \
  -H "Authorization: ApiKey $DRC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "service_name":"checkout",
    "environment":"staging",
    "tags":["release:candidate"]
  }'

Append an event:

curl -sS -X POST "$DRC_API_URL/api/v1/executions/EXECUTION_ID/events" \
  -H "Authorization: ApiKey $DRC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "id":"evt_1",
    "execution_id":"EXECUTION_ID",
    "event_type":"http_request",
    "sequence":1,
    "timestamp":1770000000000,
    "data":{"method":"GET","path":"/health"}
  }'

List filters and limits

GET /api/v1/executions supports service, execution_id, state, comma-separated event_types, limit, offset, and metadata filters. limit is between 1 and 1000; IDs are bounded to 128 characters; tags are bounded to 32 entries of 128 characters each.

Event data is bounded to 1 MiB and event metadata to 64 KiB by the documented API contract. Request bodies and causal-parent counts are also bounded by server validation. Treat these as limits, not a promise that an individual deployment has unlimited throughput.

Replays and comparisons

Create a replay:

curl -sS -X POST "$DRC_API_URL/api/v1/replays" \
  -H "Authorization: ApiKey $DRC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"execution_id":"EXECUTION_ID","mode":"strict"}'

Supported mode values in the SDK/API contract are strict, adaptive, mutated, approximate, and validation. A replay is asynchronous; persist job_id and poll until a terminal status.

**Correctness boundary:** a zero-divergence event comparison is not automatically an application-level verification. Incomplete capture, envelope-only comparison, simulation, or abstention must be surfaced as such. Use independent application tests and human review for release decisions.

Forensics and causality

Causal graph requests accept bounds such as max_nodes, max_edges, and include_sequence_edges. Bounded output is intentional for predictable API behavior.

Accounts, keys, and billing

The API also exposes authenticated account and product routes:

• POST /api/v1/accounts — account creation, subject to public-signup policy;
• POST /api/v1/accounts/login — login;
• POST /api/v1/accounts/refresh — refresh-token rotation;
• GET/PATCH /api/v1/accounts/me — current profile;
• password reset, email verification, and session revocation routes;
• GET/POST /api/v1/api-keys and DELETE /api/v1/api-keys/{id};
• GET /api/v1/dashboard, /api/v1/billing, /api/v1/billing/invoices, and /api/v1/billing/usage/timeseries.

Billing and enterprise evidence are product-access-controlled features. A route appearing in the API description does not bypass plan, tenant, role, or feature authorization.

Error envelope

{
  "error": {
    "code": "auth.header_missing",
    "category": "authentication",
    "message": "Authorization header is required",
    "request_id": "request-uuid"
  },
  "meta": {
    "api_version": "v1",
    "timestamp": 1770000000000
  }
}

Categories are authentication, authorization, validation, not_found, and internal. Useful stable codes include auth.header_missing, auth.tenant_access_denied, auth.permission_denied, execution.not_found, replay.not_found, and api.unsupported_version.

Idempotency and retries

Replay requests and asynchronous work can be retried. Persist returned job IDs, use caller-side idempotency where the deployment exposes it, and do not assume a network timeout means the job was not created. For hosted deployments, job state and result pointers must be durable and worker handlers must be idempotent.

OpenAPI and compatibility

The checked-in OpenAPI document is the machine-readable reference for the current API surface. Validate generated clients against the deployed server version and keep x-drc-api-version and stable error codes in logs. Pin the API version used by an integration and review changes before upgrading.