VeroFlag API documentation

Quick start

1. 1. Create an API key in Settings > API.
2. 2. Choose API client or agent actor type, select scopes, and choose the owner and group scope.
3. 3. Call GET /api/v1/groups to find the group id for case creation.
4. 4. Call POST /api/v1/cases with an idempotency key. The response returns a case reference and queued check references immediately.
5. 5. Poll the case or configure webhooks to receive check completion and review updates.

Authentication

API keys use bearer authentication and are shown only once when created. Store keys in a server-side secret manager and never expose them in browser or mobile clients.

Authorization: Bearer vf_live_...

Public API routes use a fixed window limit of 120 requests per 60 seconds. When the limit is exceeded, VeroFlag returns HTTP 429 with error code rate_limited and a request id for support and audit correlation.

Idempotency and retries

Mutation endpoints require an Idempotency-Key header. Use a stable key from your upstream object, such as a CRM id, case id, check id, or job id. If a network timeout happens, retry with the exact same method, path, body, and idempotency key.

# First attempt times out locally, but may still complete server-side.
curl https://veroflag.com/api/v1/cases \
  -H "Authorization: Bearer $VEROFLAG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: case-crm-12345" \
  -d @case-request.json

# Retry with the same method, path, body, and Idempotency-Key.
curl https://veroflag.com/api/v1/cases \
  -H "Authorization: Bearer $VEROFLAG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: case-crm-12345" \
  -d @case-request.json

Workspace admins can view safe per-key request metadata in Settings > API, including method, path, status, timestamp, request id, and whether an idempotency key was present. Request bodies, query strings, and authorization headers are not stored in that request log. This means raw API keys are not stored. Request metadata is retained for 90 days.

Actors and permissions

API keys can represent an API client or an agent actor. Both are first-class actors in the audit trail. Agent keys can create cases, poll checks, review matches, add materials, and enroll monitoring when permitted, but they cannot record final case decisions in the MVP.

Agents

Agent keys are intended for supervised workflow automation. Use them to gather evidence, apply deterministic policy steps, and escalate ambiguity. Do not let agents invent a final compliance conclusion or record final case decisions.

1. GET /api/v1/groups
2. POST /api/v1/cases with mode=create_or_reuse and a stable Idempotency-Key
3. Poll GET /api/v1/cases/{case_reference} or wait for check.completed webhooks
4. For each completed check, GET /api/v1/checks/{check_reference}
5. If policy allows, PATCH /api/v1/matches/{match_id}/review
6. If evidence is ambiguous, POST /api/v1/cases/{case_reference}/materials
7. Leave final case decision pending for a human or permitted API client

Endpoint examples

These examples cover every public API endpoint currently exposed. Replace sample references, group ids, and user ids with values from your workspace.

Webhooks

Configure webhook endpoints in Settings > API. VeroFlag sends signed event payloads when API-created cases, checks, match reviews, monitoring alerts, and decisions change. Public webhook-management endpoints are not exposed yet.

Summary payloads include the workspace, group, and object that changed. Expanded payloads also include event-specific fields such as case references, check references, match ids, decision values, or monitoring alert details.

Payload example

Signature verification

Error codes

Errors use a consistent envelope with an error code, message, optional details, and request id metadata.

{
  "error": {
    "code": "invalid_request",
    "message": "Case creation request is invalid.",
    "details": {
      "fieldErrors": {
        "subject": [
          "Subject name is required."
        ]
      }
    }
  },
  "meta": {
    "request_id": "req_01HX7Q3A9VY8K2M4N6P0R1S2T3"
  }
}