HTTP API reference

The DRC HTTP API is versioned under /api/v1. Use authenticated tenant context for product operations and preserve returned IDs when linking capture, replay, deployment, and evidence workflows.

Conventions

• Send JSON for POST, PUT, and PATCH requests.
• Include Authorization: Bearer <token> for hosted product operations.
• Branch on stable error.code values, not human-readable messages.
• Responses include x-drc-api-version: v1.
• Use request IDs from error responses when contacting support.

Error Codes

The API uses stable, namespaced error codes. Clients should branch on the returned error.code and treat unknown codes as failures. The full internal taxonomy is intentionally not mirrored in public documentation.

Core domains

Continuous Compliance backend contracts

CC evaluates selected machine-evaluable technical controls for a configured service. It does not certify an organization or replace an auditor. See Continuous Compliance and Continuous Verification.

• GET /api/v1/compliance/frameworks lists framework/version, technical-subset coverage, availability, disclaimer, and included versus paid entitlement.
• GET /api/v1/compliance/controls/catalog?framework=<id>&version=<version> lists control IDs, detector kind, typed evidence requirements, exact checks, entitlement, and lock reason. A control without an implemented evidence producer is unavailable and cannot be synchronized.
• GET /api/v1/compliance/overview returns selected/evaluated control state and latest server-derived evaluations.
• GET /api/v1/compliance/history returns evaluation history, evaluator version, expiration, verdict, and explanation.
• GET /api/v1/compliance/history/comparisons returns previous/current verdicts, first failure, newly failed and fixed controls, changed evidence, manifest/execution IDs, commit/dependency/configuration fingerprints, and evaluator-version changes.
• GET /api/v1/compliance/evaluations/<evaluation-id> returns expected policy, observed values, evidence IDs/links, blocker codes, remediation, evaluator version, manifest hash, evaluated commit, and environment.

Successful wording is intentionally precise: “This service passed the selected machine-evaluable technical controls in the configured framework profile.” A non-compliant result includes actionable blocker codes; missing, stale, deleted, unverifiable, or unavailable evidence never becomes a successful unknown state.

Recorded workspace surfaces

• GET /api/v1/continuous-verifications/overview returns top-level verification stats, connected repositories, and capability flags for the authenticated role.
• GET /api/v1/continuous-verifications/repositories lists only repositories in the authenticated tenant. POST /api/v1/continuous-verifications/repositories connects GitHub or Origin metadata and requires Admin; provider secrets remain in the provider adapter or worker secret store.
• GET /api/v1/continuous-verifications/repositories/{repository_id} returns that repository's verification settings, provider state, check history, captured executions, and permission-scoped capabilities. POST /api/v1/continuous-verifications/repositories/{repository_id}/captures associates a tenant-owned execution with the repository and requires ExecutionCreate.
• POST /api/v1/continuous-verifications is used by the automatic provider integration to create or reconcile a provider-owned run. Provider, provider run ID, and run attempt are integration context; customers do not select them in the CLI.
• POST /api/v1/continuous-verifications/logs reconciles the authenticated provider run from integration-supplied context and appends one bounded, idempotent log line. The client sends provider, provider run ID, run attempt, repository, commit SHA, workflow, environment, optional Signal service, phase, level, message, and client key; the user selects only the configured service. The first log creates the queued self-hosted run, while later calls reuse it.
• POST /api/v1/continuous-verifications/{id}/result records the evaluator's conclusion, check results, bounded job logs, and authenticated runtime_seconds. Runtime is rounded up per job with a one-minute minimum and recorded in the idempotent hosted compute ledger; DRC does not fabricate a conclusion while a run is queued.
• Hosted Continuous Compliance evaluates the current configured service subject. Every evaluation must include a tenant-owned finalized subject_execution_id, complete signed evidence coverage, and a complete check set. CC does not require a baseline execution. Stored results are pass or fail; an expired result is exposed as non_compliant with an evidence_expired blocker. The hosted server derives service snapshots as compliant only when every enabled control for the service profile has a fresh pass; otherwise it returns non_compliant with blocker codes. The user-facing meaning is: “This service passed the selected machine-evaluable technical controls in the configured framework profile.”
• GET /api/v1/continuous-verifications/{id}/logs returns only the authenticated tenant's recorded provider/evaluator logs.
• Evidence Packs are exposed through /api/v1/evidence/packs. Use the pack metadata, summary, contents, export, and verify routes; all access is permission-controlled and tenant-scoped.
• GET /api/v1/compliance/overview reports configured service profiles, controls, latest subject-scoped evaluations, derived service snapshots, queue state, and open alerts. drc signal cc status and drc signal cc controls read this hosted surface. A queued control test is not a verdict; only compliant or non_compliant is exposed as the service result, and a missing or incomplete subject execution is rejected before evaluation persistence.

Error envelope

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

Categories are authentication, authorization, validation, not_found, and internal. A 5xx response does not mean a request was accepted; retry only operations documented as idempotent.

Clients should handle connectivity.unsupported_integration and connectivity.integration_required explicitly. Treat unknown codes as belonging to the category supplied in the response, and display the human message only as diagnostic context.

Example: start an execution

curl -fsS https://api.example.com/api/v1/executions \
  -H 'authorization: Bearer <token>' \
  -H 'content-type: application/json' \
  -d '{"service_name":"payments-api","environment":"development"}'

The response contains the execution ID. Use it with the CLI or the hosted Workbench; do not copy raw event payloads into external issue systems.