Veriom v1 API

Base URL, authentication, request identifiers, idempotency, pagination, errors, and SSE conventions for the public REST API.

Contract-first · OpenAPI 3.1

The API base for this environment is https://api.veriom.ai/v1. Every public operation is versioned under /v1; the generated reference and typed client are built from the same public contract. Operator-only control-plane routes are intentionally excluded.

One versioned public contract

versioned routes OpenAPI 3.1 typed auth SSE progress

Browse all endpoints

Generated request, response, schema, and security documentation grouped by domain.

Audit endpoints

Create, inspect, stream, retry, cancel, and retrieve audit artifacts.

Architecture endpoints

Retrieve the evidence-backed architectural model for an audit.

Workspace Intelligence endpoints

Manage conversations, questions, run events, context search, recommendations, and assistant usage.

GitHub endpoints

Start connections, claim installations, process callbacks, and accept webhooks.

Authentication schemes

Customer browser session

The API reads the opaque veriom_session cookie. Mutations also require X-CSRF-Token and a trusted Origin. Customer sessions must not be accepted by operator endpoints.

Workspace token

Automation uses a scoped bearer token with the vat_ prefix:

Authorization: Bearer vat_<opaque-token>

Tokens expire, are hashed at rest, and are authorized only for their workspace and scopes.

Request IDs

Every response includes or returns a request ID for support and log correlation. Clients should surface it with typed errors and include it when reporting a failure. Never include OAuth codes, state values, cookies, tokens, or secret evidence in logs.

Idempotency

Long-running creations—audits, exports, and remediations—require an Idempotency-Key header. Repeating the same request returns the existing operation. Reusing the key with different input returns a typed conflict.

Idempotency-Key: unique-123

Long-running responses

Creation returns 202 Accepted with the resource identifier, current state, and status URL. Do not hold an HTTP request open for audit completion. Use the authenticated SSE feed or poll the status endpoint with bounded backoff.

Queue every repository

POST /v1/workspaces/{workspace_id}/audits/batch requires an Idempotency-Key and queues every enabled, non-archived repository on its default branch. It returns 202 Accepted with a batch_id, newly queued audits in items, and existing queued or active audits in already_active. Replaying the same key returns the original batch. Each workspace runs one audit at a time in submission order.

If a request returns 429, wait for the Retry-After interval before retrying with the same idempotency key. Polling audit progress uses a separate rate-limit bucket from audit creation.

Pagination

Collection endpoints use opaque cursor pagination. Pass the returned next_cursor unchanged; never derive or inspect its internal form.

{
  "items": [],
  "next_cursor": "opaque-or-null"
}

Typed errors

Errors include the HTTP status, stable machine code, human detail, and request ID. UI behavior branches on the stable code—not prose.

{
  "status": 409,
  "code": "source_audit_already_active",
  "detail": "This source already has an active or queued audit.",
  "request_id": "req_…",
  "existing_resource_id": "audit_…"
}

Different repositories, validated ZIP uploads, and MCP artifacts may be queued independently. A second request for the same source returns the existing audit so clients cannot accidentally create duplicate work.

SSE reconnection

Clients persist the last event ID and send it on reconnect. Event payloads are JSON and include audit ID, monotonic sequence, timestamp, type, and a typed body. Duplicate sequences are ignored client-side.

Public contract only

The reference documents customer and workspace automation capabilities. Internal deployment commands and operator control-plane operations are not part of the public API contract.