Customer developer docs

Vault API reference

Readiness, definitions, programs, runs, mappings, exceptions, sources, artifacts, and receipts.

Vault API reference

Vault is the tenant-isolated control plane. Authenticate with your tenant API key in the X-Vault-API-Key header. Responses use ISO timestamps, opaque identifiers, Cache-Control: no-store, and a structured error envelope. Requests are rate-limited per principal.

Console-only operations (definition editing, review approvals, final export authorization) additionally require a named human actor and are not available to raw API keys.

Readiness and portfolio

  • GET /v1/readiness — verdict counts, active runs, open exceptions, missing inputs, ledger integrity, program status. Metadata, never a verdict.
  • GET /v1/reporting-portfolio
  • GET /v1/reporting-entities and GET /v1/reporting-entities/{entity_id}/form-obligations

Definitions

  • GET /v1/form-definitions and GET /v1/form-definitions/{definition_id} — versioned, citation-backed definitions: Definite standard versions plus your tenant-private versions.
  • Fork, edit, and publish operations exist but are console-only; published versions are immutable and predecessors are retained.

Programs and runs

  • GET /v1/programs, POST /v1/programs, GET /v1/programs/{program_id}
  • POST /v1/programs/{program_id}/runs — body requires idempotency_key; optional trigger (manual), reporting_entity_id, form_id, form_version, reporting_period, as_of. Returns 202 with a queued run.
  • POST /v1/programs/{program_id}/run-groups — start a portfolio run group atomically.
  • GET /v1/runs, GET /v1/runs/{run_id}, POST /v1/runs/{run_id}/retry
  • GET /v1/runs/{run_id}/events — immutable stage telemetry.
  • GET /v1/runs/{run_id}/inputs — the immutable snapshot references bound to the run.
  • GET /v1/runs/{run_id}/cells and GET /v1/runs/{run_id}/cells/{concept_id} — per-cell results with lineage to receipts.
  • GET /v1/runs/{run_id}/reconciliations, GET /v1/runs/{run_id}/adjustments, POST /v1/runs/{run_id}/adjustments
  • GET /v1/runs/{run_id}/final-evidence and /final-evidence/latest, GET /v1/runs/{run_id}/agent-evidence-selections
  • GET /v1/runs/{run_id}/exports — read-only over API keys; authorizing a final export is a console action by an admin or owner. Draft exports carry a DRAFT - NOT FOR FILING watermark.

Mappings

  • GET /v1/programs/{program_id}/mapping-proposals, GET /v1/mapping-proposals/{proposal_id}
  • POST /v1/mapping-proposals/{proposal_id}/reviews, POST /v1/mapping-proposals/{proposal_id}/activate

Agent-proposed mappings are versioned and reviewed; proposal states are pending, approved, rejected, and changes_requested.

Exceptions

  • GET /v1/exceptions, GET /v1/exceptions/{exception_id}
  • PATCH /v1/exceptions/{exception_id} — assignment and state changes.
  • POST /v1/exceptions/{exception_id}/reviews — record a human review with evidence or an explanation.

Exception states: open, investigating, awaiting_human, resolved. Reviewer identity comes from the authenticated session at the console boundary; client-supplied reviewer identities are rejected.

Sources, artifacts, and receipts

  • GET /v1/data-sources — connected sources with freshness (current, late, missing, error, not_configured).
  • GET /v1/artifacts, GET /v1/artifacts/{artifact_id}, GET /v1/artifacts/{artifact_id}/lineage
  • GET /v1/receipts, GET /v1/receipts/{receipt_id} — signed rule receipts. See security for the verification procedure.

Reconciliation and financial operations

The reconciliation workspace and financial-operations surfaces in the console are backed by /v1/reconciliation/* and /v1/financial-operations/* route families (overview, accounts, work queue, transactions, exceptions, evidence, cases, matches, items, lineage, cost assurance). Match reviews and case mutations are console operations with named actors; deterministic arithmetic computes every balance status, and an agent cannot emit a verdict there either.

Onboarding and connections

/v1/onboarding-sessions and /v1/connections/* manage guided onboarding, read-only source connections, secret intents (write-only credential submission), upload intents, and connector jobs.

Error envelope

text
{
  "error": {
    "code": "SOURCE_SNAPSHOT_REQUIRED",
    "message": "no immutable source snapshot is available for this program",
    "request_id": "request-id"
  }
}

Every error carries a code, a message, and the request_id to reference in support requests.

Retired routes

Endpoints from earlier product generations (policy evaluation, generic evidence checks, governance registries, /v1/report-programs, /v1/cc) return 410 GONE with an explanatory error. Use the routes on this page.