ProjexCloud — API Reference

Activates an active-active multi-region profile for a tenant (P8 Variant D): home region, the list of paired regions, the contractual addendum that authorizes it, optional RPO/RTO targets and optional per-stream replication overrides (sync | async | single-region). Returns 201 { success: true, data: <profile> }. QA edge cases: tenant_id, home_region, contract_addendum_ref are falsy-checked and paired_regions must pass Array.isArray — note an EMPTY array passes the guard, so [] is accepted and produces a profile with no pairs; there is no check that home_region is excluded from paired_regions or that any region actually exists, so nonsense regions are only caught (if at all) at the DB layer as a 500; rpo_target_seconds/rto_target_seconds are unvalidated (negative and zero accepted); replication_overrides values are not enum-checked in the route; re-activating an existing tenant profile has no conflict branch and may raise a unique violation as a 500 rather than 409.

[
  "POST /api/auth/signup-tenant"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "home_region": "us-east-1",
  "paired_regions": [
    "us-west-2",
    "eu-west-1"
  ],
  "contract_addendum_ref": "addendum-2026-DR-001",
  "rpo_target_seconds": 5,
  "rto_target_seconds": 60,
  "replication_overrides": {
    "sdk-billing": "sync",
    "sdk-analytics": "async"
  }
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "home_region": "us-east-1",
  "paired_regions": [
    "us-west-2",
    "eu-west-1"
  ],
  "contract_addendum_ref": "addendum-2026-DR-001",
  "rpo_target_seconds": 5,
  "rto_target_seconds": 60,
  "replication_overrides": {
    "sdk-billing": "sync",
    "sdk-analytics": "async"
  }
}

{
  "success": true,
  "data": {
    "profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "home_region": "us-east-1",
    "paired_regions": [
      "us-west-2",
      "eu-west-1"
    ],
    "contract_addendum_ref": "addendum-2026-DR-001",
    "rpo_target_seconds": 5,
    "rto_target_seconds": 60,
    "replication_overrides": {
      "sdk-billing": "sync",
      "sdk-analytics": "async"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "profile_id": "string",
    "tenant_id": "string",
    "tier": "string",
    "home_region": "string",
    "paired_regions": "array",
    "rpo_target_seconds": "number",
    "rto_target_seconds": "number",
    "contract_addendum_ref": "string",
    "activated_at": "string"
  }
}

Runs a failover drill against an active-active profile, moving traffic to to_region (optionally declaring from_region) and recording the measured result; returns 201 { success: true, data: <drill> }. QA edge cases: only to_region is required — from_region is optional and inferred when omitted, so a minimal body is just { to_region }; there is no validation that to_region is one of the profile's paired_regions, nor that it differs from from_region, so a drill to an unpaired region is not a 400 and either succeeds meaninglessly or fails as a 500; an unknown profile_id has no 404 branch and surfaces as a 500 with the raw message; the drill is a real state-changing operation and is NOT idempotent — every call records a new drill row and may actually move traffic, so it should not be replayed casually in a shared environment.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/active-active/profiles"
]

{
  "profile_id": "{{cache:active-active-profiles.create.response.data.profile_id}}"
}

{
  "to_region": "us-west-2",
  "from_region": "us-east-1"
}

{
  "to_region": "us-west-2",
  "from_region": "us-east-1"
}

{
  "success": true,
  "data": {
    "status": "completed",
    "to_region": "us-west-2",
    "from_region": "us-east-1",
    "drill_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "drill_id": "string",
    "profile_id": "string",
    "from_region": "string",
    "to_region": "string",
    "started_at": "string",
    "rpo_observed_seconds": "number",
    "rto_observed_seconds": "number",
    "passed": "boolean",
    "audit_entry_id": "string",
    "tier_downgrade_triggered": "boolean"
  }
}

Reads a tenant's active-active profile together with its replication streams, returning { success: true, data: { profile, replication_streams } }. QA edge cases: a tenant with no profile is a clean 404 "no profile for tenant" — the null check on the profile happens before the stream lookup, so streams are only queried for a real profile; a profile that exists with zero replication streams is a 200 with an empty replication_streams array, not a 404; neither call is wrapped in try/catch, so a tenant_id that fails the Postgres uuid cast escapes to the Fastify default 500 body ({ statusCode, error, message }) rather than a 400 or 404; the route is cross-tenant and ops-token gated, so the tenant_id path param is trusted with no ownership check against a caller JWT.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/active-active/profiles"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "success": true,
  "data": {
    "profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "profile not found"
}

{
  "data": {
    "profile": {
      "profile_id": "string",
      "tenant_id": "string",
      "tier": "string",
      "home_region": "string",
      "paired_regions": "array"
    },
    "replication_streams": "array"
  }
}

Operator SLA-breach report: pending approval requests whose elapsed time since requested_at exceeds their route's SLA, exposing request_id, tenant_id, route_id, a subject_ref built as subject_kind:subject_id, requested_at, status, elapsed_minutes and sla_minutes, worst-breach-first and capped at 100 rows. QA edge cases: only requests with status = "pending" are considered, so a request that breached its SLA and was later approved or rejected disappears from this report entirely; routes whose computed sla_minutes is 0 (no per-step SLA set, since the value is COALESCE'd to 0) are excluded by the sla_minutes > 0 filter and can never breach; the comparison is strictly greater-than, so a request exactly at its SLA is not yet a breach; elapsed_minutes is computed from now() at query time and therefore changes between calls; cross-tenant with no tenant filter and no pagination past 100 rows.

{
  "success": true,
  "data": [
    {
      "breach_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Operator break-glass override of a pending approval request: forces the decision to approved or rejected, stamps resolved_at, and rewrites the reason as "[operator-override by <operator_id>] <reason>" so the override is self-evident in the audit trail. Returns a bare { success: true } with no data. QA edge cases: the UPDATE is guarded by "WHERE request_id = $1 AND status = 'pending'", but the handler NEVER inspects the affected row count — so overriding an unknown request_id, or one that is already approved/rejected, still returns 200 { success: true } while changing nothing. There is no 404 and no 409; QA must verify the effect by re-reading the request rather than trusting the status code. decision, reason and operator_id are all required by a falsy check, and decision is not enum-validated in the route, so a value other than approved/rejected is written straight into status.

[
  "POST /api/auth/signup-tenant",
  "POST /api/approvals/routes",
  "POST /api/approvals/requests"
]

{
  "entity": "approval.request",
  "field": "status",
  "flow": [
    "pending",
    "approved",
    "rejected"
  ],
  "transitions": [
    {
      "from": "pending",
      "to": "approved",
      "via": "POST /admin/approvals/requests/:request_id/operator-override"
    },
    {
      "from": "pending",
      "to": "rejected",
      "via": "POST /admin/approvals/requests/:request_id/operator-override"
    }
  ]
}

{
  "request_id": "{{cache:approvals.requests.create.response.data.request.request_id}}"
}

{
  "decision": "approved",
  "reason": "Operator override — SLA breach escalation resolved out-of-band",
  "operator_id": "{{var:operator_id}}"
}

{
  "decision": "approved",
  "reason": "Operator override — SLA breach escalation resolved out-of-band",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "operator_override_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "decision": "approved",
    "reason": "Operator override — SLA breach escalation resolved out-of-band",
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Operator cross-tenant listing of approval routes — route_id, tenant_id, name, status, created_at and a derived sla_minutes computed as the MAX sla_minutes across the route's steps JSON array — newest-first and capped at 200 rows. QA edge cases: sla_minutes is COALESCE'd to 0, so a route whose steps carry no sla_minutes reports 0 rather than null, and 0 is also what the breaches query treats as "no SLA" (such routes can never appear as breached); the derived value is the maximum across steps, not per-step, so per-step SLAs are not visible here; no filtering by tenant or status and no pagination past the 200-row cap; an empty result is a 200 with data: [], never 404; a malformed steps JSON in a row can fail jsonb_array_elements and turn the whole request into a 500.

{
  "success": true,
  "data": [
    {
      "route_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Provisions the parent app (and its owning org) that a tenant references via tenant.app_id, returning 201 { data: { app } }. Deliberately idempotent: appEnsure() returns the existing app unchanged when app_id already exists, so replaying the same body is safe and still answers 201 (not 409). This exists because without it there is no admin path to create the first app and POST /admin/tenants always fails its FK. QA edge cases: app_id and display_name are required and empty strings are rejected as missing; org_name is optional and only used on first creation — re-posting with a different org_name does NOT re-parent an existing app; changing display_name on a replay may or may not update depending on appEnsure semantics, so assert against the returned row rather than the request body.

{
  "app_id": "{{dynamic:name}}",
  "display_name": "QA Admin App",
  "org_name": "QA Admin Org"
}

{
  "app_id": "Acme QA Sample",
  "display_name": "QA Admin App",
  "org_name": "QA Admin Org"
}

{
  "success": true,
  "data": {
    "app_id": "Acme QA Sample",
    "display_name": "QA Admin App",
    "org_name": "QA Admin Org",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "app": {
      "app_id": "string",
      "org_id": "string",
      "display_name": "string",
      "status": "string",
      "created_at": "string"
    }
  }
}

Browses the audit chain across tenants with optional tenant_id, actor_id, from and to filters, returning entry_id, tenant_id, actor_kind, actor_id, event_type, occurred_at and seq, newest-first. limit defaults to 100 and is clamped to a maximum of 500 — a larger value is silently reduced rather than rejected. QA edge cases: a non-numeric limit makes parseInt return NaN, and Math.min(NaN, 500) is NaN, which is passed as the LIMIT parameter and fails in Postgres as a 500 — so limit=abc is a server error, not a 400; there is no offset or cursor, so paging deeper than the limit is impossible; tenant_id must be a valid UUID or the ::uuid cast fails as a 500, and from/to must be castable to timestamptz for the same reason; with no filters the route returns entries across ALL tenants, which is deliberate for an operator surface.

[
  "POST /api/auth/signup-tenant"
]

{
  "success": true,
  "data": [
    {
      "entry_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": "array"
}

Fetches a single audit entry by entry_id with SELECT *, so the response includes the full row — payload plus the chain fields seq, prev_hash and entry_hash that POST /admin/audit/verify walks. Returns { success: true, data: <entry> }. QA edge cases: an unknown entry_id is a clean 404 "entry not found" from an explicit row-count check; an entry_id that is not castable to the column type (e.g. a non-UUID when the column is a UUID) fails in Postgres and returns 500 rather than 400 or 404, so malformed and missing ids behave differently here — unlike GET /admin/invoices/:invoice_id which regex-checks first and 404s; the hash columns come back as bytea and serialize as buffer-shaped JSON, not hex strings; the route is cross-tenant and ops-token gated, so no tenant ownership check is applied.

[
  "POST /api/auth/signup-tenant",
  "POST /api/audit/append"
]

{
  "entry_id": "{{cache:audit.append.response.data.entry_id}}"
}

{
  "success": true,
  "data": {
    "entry_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "entry not found"
}

{
  "data": {
    "entry_id": "string",
    "tenant_id": "string",
    "actor_kind": "string",
    "actor_id": "string",
    "action": "string",
    "occurred_at": "string",
    "seq": "number"
  }
}

Verifies the integrity of a tenant's audit hash chain: loads every entry for the tenant ordered by seq and walks it, requiring seq to be contiguous from 0 and each entry's prev_hash to equal the previous entry's entry_hash (the first entry must link to 32 zero bytes). tenant_id is a QUERY parameter, not a body field, and is mandatory. QA edge cases: a FAILED verification is NOT an error status — it returns 200 with { verified: false, failed_seq, reason: "gap" | "wrong-prev" }, so tests must assert on the payload, not the HTTP code; a tenant with zero entries verifies as true with entry_count 0; the walk loads the entire chain with no LIMIT, so a large tenant makes this a slow, memory-heavy call; a tenant_id that is not a valid UUID fails the ::uuid cast and returns 500 rather than 400.

[
  "POST /api/auth/signup-tenant"
]

{}

{
  "success": true,
  "data": {
    "status": "completed",
    "verify_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "verified": "boolean",
    "entry_count": "number"
  }
}

Binds a tenant to a customer-managed KMS key (P8 Variant A · BYOK), recording provider, customer_kms_key_arn, tenant_key_id, the revoke-propagation SLA and an optional SIEM forwarder endpoint, and returns 200 { success: true, data: <binding> }. QA edge cases: tenant_id, provider, customer_kms_key_arn, tenant_key_id and operator_id are all required with a falsy check (empty strings rejected); provider is typed as aws-kms|gcp-kms|hsm-pkcs11 but NOT validated at runtime by the route, so an unknown provider reaches bindCmk and fails as a 500 rather than a 400; the ARN is not format-checked and the key is not proven reachable at bind time; binding a tenant that already has a binding is not given a 409 branch here — whatever bindCmk does (replace or unique violation) determines whether you see a 200 or a 500; sla_revoke_propagation_seconds and siem_forwarder_endpoint are optional and unbounded.

[
  "POST /api/auth/signup-tenant"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "provider": "aws-kms",
  "customer_kms_key_arn": "{{var:customer_kms_key_arn}}",
  "tenant_key_id": "{{var:tenant_key_id}}",
  "sla_revoke_propagation_seconds": 30,
  "siem_forwarder_endpoint": "https://siem.qa.example.com/ingest",
  "operator_id": "{{var:operator_id}}"
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "provider": "aws-kms",
  "customer_kms_key_arn": "{{var:customer_kms_key_arn}}",
  "tenant_key_id": "{{var:tenant_key_id}}",
  "sla_revoke_propagation_seconds": 30,
  "siem_forwarder_endpoint": "https://siem.qa.example.com/ingest",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "provider": "aws-kms",
    "customer_kms_key_arn": "{{var:customer_kms_key_arn}}",
    "tenant_key_id": "{{var:tenant_key_id}}",
    "sla_revoke_propagation_seconds": 30,
    "siem_forwarder_endpoint": "https://siem.qa.example.com/ingest",
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "binding_id": "string",
    "tenant_id": "string",
    "provider": "string",
    "customer_kms_key_arn": "string",
    "tenant_key_id": "string",
    "grant_status": "string",
    "bound_at": "string",
    "revoked_at": "string",
    "sla_revoke_propagation_seconds": "number",
    "siem_forwarder_endpoint": "string"
  }
}

Revokes a tenant CMK binding, recording the mandatory reason and operator_id for the audit trail, and returns 200 { success: true, data: <binding> } with the now-revoked binding. QA edge cases: reason and operator_id are both required with a falsy check (empty strings rejected) — revocation is never allowed to be unattributed; an unknown binding_id is a clean 404 "binding not found" because revokeCmk() returning null is handled explicitly, unlike the sibling rotate route which 500s in the same situation; revoking an already-revoked binding depends on revokeCmk returning the row (200) versus null (404), so assert on the returned status rather than assuming idempotency; propagation to readers is bounded by the binding's sla_revoke_propagation_seconds, so a revoked key can still decrypt for a short window after this call returns 200.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/byok/bindings"
]

{
  "entity": "byok_binding",
  "field": "grant_status",
  "flow": [
    "active",
    "revoking",
    "revoked"
  ],
  "transitions": [
    {
      "from": "active",
      "to": "revoking",
      "via": "POST /admin/byok/bindings/:binding_id/revoke"
    },
    {
      "from": "revoking",
      "to": "revoked",
      "via": "POST /admin/byok/bindings/:binding_id/revoke"
    }
  ]
}

{
  "binding_id": "{{cache:byok-bindings.create.response.data.binding_id}}"
}

{
  "reason": "QA automated revoke drill",
  "operator_id": "{{var:operator_id}}"
}

{
  "reason": "QA automated revoke drill",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "status": "completed",
    "reason": "QA automated revoke drill",
    "operator_id": "{{var:operator_id}}",
    "revoke_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "binding_id": "string",
    "tenant_id": "string",
    "grant_status": "string",
    "revoked_at": "string"
  }
}

Rotates a tenant CMK: re-wraps material from previous_tenant_key_id to new_tenant_key_id for the binding named in the path, attributing the action to operator_id, and returns 200 { success: true, data: <rotation> }. QA edge cases: all three body fields are required with a falsy check; the distinctive failure is UndecryptableError — raised when data cannot be re-wrapped under the new key (wrong previous key, revoked/deleted customer key, KMS denying access) — which the handler maps to the error's own status_code or 409 when it has none, so QA must expect a 409-class conflict there rather than a 500; every other throw (unknown binding_id, KMS outage, DB failure) collapses into a 500 with the raw message and there is no 404 branch, so rotating a non-existent binding_id is a 500; a repeated rotation with the same previous/new pair is not idempotent and will typically fail undecryptable on the second run because the previous key no longer wraps anything.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/byok/bindings"
]

{
  "binding_id": "{{cache:byok-bindings.create.response.data.binding_id}}"
}

{
  "previous_tenant_key_id": "{{var:tenant_key_id}}",
  "new_tenant_key_id": "{{var:new_tenant_key_id}}",
  "operator_id": "{{var:operator_id}}"
}

{
  "previous_tenant_key_id": "{{var:tenant_key_id}}",
  "new_tenant_key_id": "{{var:new_tenant_key_id}}",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "status": "completed",
    "previous_tenant_key_id": "{{var:tenant_key_id}}",
    "new_tenant_key_id": "{{var:new_tenant_key_id}}",
    "operator_id": "{{var:operator_id}}",
    "rotate_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "rotation_id": "string",
    "binding_id": "string",
    "started_at": "string",
    "completed_at": "string",
    "previous_tenant_key_id": "string",
    "new_tenant_key_id": "string",
    "leaf_reencryption_needed": "boolean"
  }
}

Reads the current BYOK binding for a single tenant, returning { success: true, data: <binding> } or 404 when the tenant has never been bound. QA edge cases: the "no binding" case is an explicit 404 with error "no binding for tenant", so absence is distinguishable from a bad request; the lookup is NOT wrapped in try/catch, so a tenant_id that is not a well-formed UUID fails the Postgres uuid cast and escapes to the Fastify default 500 body ({ statusCode, error, message }) instead of a 400 or the { success: false, error } envelope — this is the most common surprise when testing with a non-UUID path param; the route is ops-token gated and cross-tenant, so the tenant_id in the path is trusted with no ownership check against a caller JWT; a revoked binding is still returned as data (with its revoked state) rather than 404.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/byok/bindings"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "success": true,
  "data": {
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "tenant not found"
}

{
  "data": {
    "binding_id": "string",
    "tenant_id": "string",
    "provider": "string",
    "grant_status": "string"
  }
}

Runs an operator-triggered federation chaos drill (P7 FR-FED-3 / AC-6): performs a failover from from_region to to_region for the given federation and records a failover_event with trigger="chaos-drill" so monthly RPO/RTO drills produce auditable, production-condition numbers. Returns 200 { success: true, data: <failover event> }. QA edge cases: all three of federation_id, from_region and to_region are required and empty strings count as missing; there is no check that from_region differs from to_region, nor that either region is a member of the federation — an unknown federation_id or region surfaces from the orchestrator as a 500 with the raw message rather than a 404; each call writes a new failover_event, so it is NOT idempotent and repeated drills accumulate rows; this route depends on the gateway-internal orchestrator started at boot (FEDERATION_ORCHESTRATOR_ENABLED), unlike POST /admin/chaos-drill which has no orchestrator in the gateway mount.

{
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2"
}

{
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2"
}

{
  "success": true,
  "data": {
    "chaos_drill_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "federation_id": "{{var:federation_id}}",
    "from_region": "us-east-1",
    "to_region": "us-west-2",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Hot-reloads the active Iceberg backend driver in the running gateway without a restart, so ops can flip drivers (nessie ↔ glue) or refresh credentials in place. Returns { success: true, data: { driver } } echoing the now-active driver. QA edge cases: the change is process-local and in-memory — in a multi-replica deployment only the replica that served the request is reconfigured, and the setting does not survive a restart; driver is the only required field and is not checked against an enum by the route, so an unknown/misconfigured driver is rejected by bootstrapIcebergBackend() and mapped to 400 (not 500) along with any credential/connection setup error it throws; a successful call has no 201 semantics and returns plain 200.

{
  "driver": "none",
  "base_url": "https://nessie.example.com/api/v1",
  "bearer_token": "{{static:test-bearer-token}}"
}

{
  "driver": "none",
  "base_url": "https://nessie.example.com/api/v1",
  "bearer_token": "test-bearer-token"
}

{
  "success": true,
  "data": {
    "iceberg_backend_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "driver": "none",
    "base_url": "https://nessie.example.com/api/v1",
    "bearer_token": "test-bearer-token",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers (or updates) a federation.iceberg_table_binding row mapping a ClickHouse source table onto an Iceberg table_ref within a catalog. Upsert on binding_id: ON CONFLICT DO UPDATE rewrites catalog_id, table_ref, source_clickhouse_table, partition_strategy and z_order_cols, so a repeat post is an update and still returns 201. partition_strategy defaults to {} and is stored as jsonb; z_order_cols defaults to []. QA edge cases: binding_id, catalog_id and table_ref are required (empty strings count as missing); catalog_id is a foreign key onto federation.iceberg_catalog, so binding to a catalog that was never registered surfaces as a 500 with the raw FK message, NOT a 400 or 404 — register the catalog first; partition_strategy is JSON.stringify-ed without shape validation, so any object is accepted; source_clickhouse_table is optional and stored as NULL when omitted.

[
  "POST /admin/federation/iceberg-catalogs"
]

{
  "binding_id": "qa-iceberg-binding-1",
  "catalog_id": "{{cache:federation-iceberg-catalogs.create.response.data.catalog_id}}",
  "table_ref": "warehouse.usage_events",
  "source_clickhouse_table": "meter.usage_ledger",
  "partition_strategy": {
    "region": "identity",
    "tenant": "identity",
    "time": "day"
  },
  "z_order_cols": [
    "tenant_id",
    "sku"
  ]
}

{
  "binding_id": "qa-iceberg-binding-1",
  "catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "table_ref": "warehouse.usage_events",
  "source_clickhouse_table": "meter.usage_ledger",
  "partition_strategy": {
    "region": "identity",
    "tenant": "identity",
    "time": "day"
  },
  "z_order_cols": [
    "tenant_id",
    "sku"
  ]
}

{
  "success": true,
  "data": {
    "iceberg_binding_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "binding_id": "qa-iceberg-binding-1",
    "catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "table_ref": "warehouse.usage_events",
    "source_clickhouse_table": "meter.usage_ledger",
    "partition_strategy": {
      "region": "identity",
      "tenant": "identity",
      "time": "day"
    },
    "z_order_cols": [
      "tenant_id",
      "sku"
    ],
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Lists every registered Iceberg catalog (catalog_id, region, backend, root_url, capacity_tier, status, created_at) newest-first as { success: true, data: rows }. Cross-tenant operator view with no filtering, no pagination and no row limit — the full federation.iceberg_catalog table is returned, so response size grows unbounded with catalog count. QA edge cases: the query is NOT wrapped in try/catch, so a database failure escapes to the Fastify default error handler and returns the framework-shaped 500 body ({ statusCode, error, message }) rather than the { success: false, error } shape the sibling routes use — assert accordingly; an empty table is a 200 with data: [], not a 404.

{
  "success": true,
  "data": [
    {
      "iceberg_catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers (or updates) a federation.iceberg_catalog row so the lineage-projector worker can resolve a target table_ref, giving ops an alternative to raw SQL and preserving the auto-migrate doctrine. Upsert semantics: ON CONFLICT (catalog_id) DO UPDATE overwrites region, backend, root_url, capacity_tier and status, so re-posting an existing catalog_id is an update and still returns 201, never 409. capacity_tier defaults to "standard" and status to "active". QA edge cases: backend is validated against the closed set glue|nessie|hive and anything else is a 400; catalog_id, region, backend and root_url are all required and empty strings count as missing; root_url is not URL-validated; status is NOT validated in the handler, so an out-of-enum status reaches the DB check constraint and returns 500 rather than 400.

{
  "catalog_id": "qa-iceberg-catalog-useast",
  "region": "us-east-1",
  "backend": "nessie",
  "root_url": "https://nessie.example.com/api/v1",
  "capacity_tier": "standard",
  "status": "active"
}

{
  "catalog_id": "qa-iceberg-catalog-useast",
  "region": "us-east-1",
  "backend": "nessie",
  "root_url": "https://nessie.example.com/api/v1",
  "capacity_tier": "standard",
  "status": "active"
}

{
  "success": true,
  "data": {
    "iceberg_catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "catalog_id": "qa-iceberg-catalog-useast",
    "region": "us-east-1",
    "backend": "nessie",
    "root_url": "https://nessie.example.com/api/v1",
    "capacity_tier": "standard",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Read-only probe counter for the federation failover orchestrator: returns { success: true, data: <stats> } straight from the in-memory handle (probe counts, failure streaks, last-run bookkeeping) with no database access. QA edge cases: the numbers are per-replica and per-process — they reset to zero on every gateway restart and differ between replicas behind the load balancer, so tests must not assert absolute counts across calls; with FEDERATION_ORCHESTRATOR_ENABLED=false the orchestrator is constructed but idle and stats stay at their initial values rather than the route 404-ing or erroring; the handler has no try/catch and no failure branch beyond the auth guard, so 401 and 200 are the only realistic outcomes.

{
  "success": true,
  "data": [
    {
      "orchestrator_stat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Cross-tenant operator listing of billing invoices with optional tenant_id, from and to filters, newest-first by generated_at and hard-capped at 200 rows. The date filters are inclusive-overlap, not containment: from matches invoices whose period_end >= from and to matches invoices whose period_start <= to, so a range returns every invoice overlapping it. QA edge cases: there is no pagination or cursor, so beyond 200 invoices the tail is invisible; omitting tenant_id returns invoices for ALL tenants — this route is deliberately not tenant-scoped and is ops-token gated only; a tenant_id that is not a valid UUID fails the ::uuid cast and returns 500 (not 400), and an unparseable from/to fails the ::date cast the same way; filters that match nothing are a 200 with an empty array, never 404.

[
  "POST /api/auth/signup-tenant"
]

{
  "success": true,
  "data": [
    {
      "invoice_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Returns one invoice with all of its line items, as { success: true, data: { invoice, line_items } }, line items ordered by sku. QA edge cases: invoice_id is checked against a strict UUID regex BEFORE any query runs and a non-UUID is answered 404 "invoice not found" rather than 400 — so malformed and non-existent ids are indistinguishable by design (this deliberately prevents id-format probing); a well-formed UUID with no matching row gets the same 404; an invoice that exists with zero line items is a 200 with an empty line_items array, not a 404; the invoice row is selected with SELECT *, so the payload includes every column including internal billing state; the route is cross-tenant and ops-token gated, so no tenant ownership check is applied to the requested invoice.

[
  "POST /api/billing/invoices/generate"
]

{
  "invoice_id": "{{cache:billing-invoices.generate.response.data.invoice.invoice_id}}"
}

{
  "success": true,
  "data": {
    "invoice_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "invoice not found"
}

Operator-triggered lineage backfill (P6B FR-LIN-5 / TK-3380). Resumable via a per-(pool_index, event_type) checkpoint so an interrupted run continues where it stopped rather than restarting; dry_run (default false) reports the counts it would write without writing anything. All body fields are optional — with an empty body the backfill runs across every pool and event_type from the stored checkpoint. QA edge cases: there is NO field validation, so an unknown pool_index or event_type is not a 400 — it simply matches nothing and returns a zero-count success; from/to are passed through new Date() unchecked, so an unparseable string becomes Invalid Date and surfaces as a 500 from the query layer; batch_size is unbounded, so a very large value can hold a connection long enough to exhaust the pool; a non-dry-run backfill advances the checkpoint, which makes a second identical call return far smaller counts — assert relative, not absolute.

{
  "pool_index": "{{var:pool_index}}",
  "event_type": "ai-gateway.complete.v1",
  "batch_size": 500,
  "dry_run": true,
  "from": "{{dynamic:pastdatetime}}",
  "to": "{{dynamic:futuredatetime}}"
}

{
  "pool_index": "{{var:pool_index}}",
  "event_type": "ai-gateway.complete.v1",
  "batch_size": 500,
  "dry_run": true,
  "from": "2026-01-15T10:30:00Z",
  "to": "2026-01-15T10:30:00Z"
}

{
  "success": true,
  "data": {
    "backfill_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pool_index": "{{var:pool_index}}",
    "event_type": "ai-gateway.complete.v1",
    "batch_size": 500,
    "dry_run": true,
    "from": "2026-01-15T10:30:00Z",
    "to": "2026-01-15T10:30:00Z",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Grants a time-boxed operator override of a metering hard cap for one tenant + SKU, lifting the block until the "until" timestamp with a mandatory operator_id and reason for the audit trail; the x-trace-id request header is threaded through when present. Returns 200 { success: true, data: <override> }. QA edge cases: all five of tenant_id, sku, until, operator_id and reason are required with a falsy check — an override can never be unattributed or open-ended; "until" is passed through as a string with no parsing or future-dating check in the route, so an unparseable timestamp or one already in the past is not a 400 and either fails the timestamptz cast as a 500 or is stored as an immediately-expired override that silently does nothing; sku is not validated against the known SKU set; re-issuing an override for the same tenant+sku typically supersedes or duplicates depending on applyHardCapOverride, with no 409 branch in the route.

[
  "POST /api/auth/signup-tenant"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "sku": "ai.gateway.tokens.input",
  "until": "{{dynamic:futuredatetime}}",
  "operator_id": "{{var:operator_id}}",
  "reason": "Temporary lift while billing negotiates an upgrade"
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sku": "ai.gateway.tokens.input",
  "until": "2026-01-15T10:30:00Z",
  "operator_id": "{{var:operator_id}}",
  "reason": "Temporary lift while billing negotiates an upgrade"
}

{
  "success": true,
  "data": {
    "override_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sku": "ai.gateway.tokens.input",
    "until": "2026-01-15T10:30:00Z",
    "operator_id": "{{var:operator_id}}",
    "reason": "Temporary lift while billing negotiates an upgrade",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Lists every metering pricing catalog (P7 Y-11) backing the Admin UI as { success: true, data: catalogs }. Read-only operator surface with no filtering, no pagination and no limit, and gated by the requireAdmin ops-token helper rather than a tenant JWT. QA edge cases: the listPricingCatalogs() call is NOT wrapped in try/catch, so a DB failure escapes to the Fastify default error handler and produces the framework 500 body ({ statusCode, error, message }) instead of the { success: false, error } envelope used elsewhere; catalogs of every status (draft, active, retired) are returned together with no status filter, so tests that expect only active catalogs must filter client-side; an empty result is a 200 with an empty array, never 404.

{
  "success": true,
  "data": [
    {
      "pricing_catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Creates a new version of a pricing catalog, stamping created_by from operator_id, and returns 200 { success: true, data: <created version> }. QA edge cases: catalog_id, version and operator_id are all required and validated with a falsy check — which means version: 0 is rejected as missing even though it is a valid-looking integer, and empty strings are likewise rejected; version is not type-checked, so a string version is passed straight to the DB; re-creating an existing (catalog_id, version) pair violates the uniqueness constraint and surfaces as a 500 with the raw driver message rather than a 409 — there is no conflict branch in this handler; nothing verifies operator_id corresponds to a real operator, it is recorded as free text.

[
  "POST /api/auth/signup-tenant"
]

{
  "catalog_id": "qa-pricing-catalog-{{dynamic:slug}}",
  "version": 1,
  "operator_id": "{{var:operator_id}}"
}

{
  "catalog_id": "qa-pricing-catalog-{{dynamic:slug}}",
  "version": 1,
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "pricing_catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "catalog_id": "qa-pricing-catalog-{{dynamic:slug}}",
    "version": 1,
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Fetches one pricing catalog plus its associated rates by catalog_id, returning { success: true, data: { catalog, ... } }. QA edge cases: a catalog_id that does not exist yields 404 "catalog not found" — the handler explicitly checks result.catalog for null, so a catalog row that exists with zero rates is still a 200 (empty rate collection), not a 404; catalog_id is taken from the path verbatim with no format validation, so arbitrary strings are looked up and simply miss; getPricingCatalog() itself is NOT inside a try/catch, so a database error escapes to the Fastify default 500 shape rather than the { success: false, error } envelope; the route is ops-token gated and returns 401 before ever touching the DB.

[
  "POST /admin/meter/pricing-catalogs"
]

{
  "catalog_id": "{{cache:meter-pricing-catalogs.create.response.data.catalog_id}}"
}

{
  "success": true,
  "data": {
    "pricing_catalog_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "pricing_catalog not found"
}

Upserts the price rate for a single SKU inside a pricing catalog (P7 Y-11), keyed by the catalog_id and sku path params, returning 200 { success: true, data: <upserted rate> }. Because it is an upsert it is idempotent: repeating the same PUT overwrites rather than conflicting. price, margin_pct and tiers are optional and coerced to null when omitted, so a body with only unit/mode/operator_id clears any previously set price and margin. QA edge cases: unit, mode and operator_id are required and empty strings count as missing; mode is not validated against an enum in the route, so an unsupported mode reaches the DB check constraint and returns 500 rather than 400; a catalog_id that does not exist is NOT a 404 — the FK violation surfaces as a 500; tiers is accepted as arbitrary unvalidated JSON; writing to a retired or non-draft catalog is not blocked by this handler.

[
  "POST /admin/meter/pricing-catalogs"
]

{
  "catalog_id": "{{cache:meter-pricing-catalogs.create.response.data.catalog_id}}",
  "sku": "ai.gateway.tokens.input"
}

{
  "unit": "token",
  "mode": "per_unit",
  "price": 0.0025,
  "margin_pct": 15,
  "tiers": [
    {
      "up_to": 100000,
      "unit_price": 0.0025
    },
    {
      "up_to": null,
      "unit_price": 0.002
    }
  ],
  "operator_id": "{{var:operator_id}}"
}

{
  "unit": "token",
  "mode": "per_unit",
  "price": 0.0025,
  "margin_pct": 15,
  "tiers": [
    {
      "up_to": 100000,
      "unit_price": 0.0025
    },
    {
      "up_to": null,
      "unit_price": 0.002
    }
  ],
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "rate_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unit": "token",
    "mode": "per_unit",
    "price": 0.0025,
    "margin_pct": 15,
    "tiers": [
      {
        "up_to": 100000,
        "unit_price": 0.0025
      },
      {
        "up_to": null,
        "unit_price": 0.002
      }
    ],
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Transitions a pricing catalog between draft, active and retired, returning a bare { success: true } with no data payload. QA edge cases: this handler does NOT verify the catalog exists first — setCatalogStatus() against an unknown catalog_id updates zero rows and still answers 200 { success: true }, so QA cannot use this route to probe existence and must confirm the change with GET /admin/meter/pricing-catalogs/:catalog_id; status and operator_id are required by a falsy check but status is not validated against the draft|active|retired enum in the route, so an out-of-enum value reaches the DB check constraint and returns 500 rather than 400; there is no state-machine guard, so retired → active is accepted; the transition is idempotent — setting the status a catalog already has succeeds.

[
  "POST /admin/meter/pricing-catalogs"
]

{
  "entity": "pricing_catalog",
  "field": "status",
  "flow": [
    "draft",
    "active",
    "retired"
  ],
  "transitions": [
    {
      "from": "draft",
      "to": "active",
      "via": "PATCH /admin/meter/pricing-catalogs/:catalog_id/status"
    },
    {
      "from": "active",
      "to": "retired",
      "via": "PATCH /admin/meter/pricing-catalogs/:catalog_id/status"
    }
  ]
}

{
  "catalog_id": "{{cache:meter-pricing-catalogs.create.response.data.catalog_id}}"
}

{
  "status": "active",
  "operator_id": "{{var:operator_id}}"
}

{
  "status": "active",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "statu_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "operator_id": "{{var:operator_id}}",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers a customer on-prem install (P8 Variant C) with its cluster name, Kubernetes distribution and installed version, returning 201 { success: true, data: <install> }. air_gap_mode (strict | diode-in | diode-bidi) and billing_mode (internal-report-only | flat-fee | per-incident) are optional and default inside registerOnpremInstall. QA edge cases: customer_id, cluster_name, k8s_distribution and installed_version are required with a falsy check (empty strings rejected); k8s_distribution, air_gap_mode and billing_mode are typed unions but are NOT runtime-validated by the route, so out-of-enum values reach the DB check constraints and return 500 rather than 400; the route is not idempotent — registering the same customer_id + cluster_name twice either creates a second install or raises a unique violation as a 500, since there is no conflict branch; installed_version is free text and not semver-validated.

{
  "customer_id": "{{var:customer_id}}",
  "cluster_name": "{{dynamic:name}}",
  "k8s_distribution": "openshift",
  "installed_version": "2026.3.0",
  "air_gap_mode": "diode-in",
  "billing_mode": "internal-report-only"
}

{
  "customer_id": "{{var:customer_id}}",
  "cluster_name": "Acme QA Sample",
  "k8s_distribution": "openshift",
  "installed_version": "2026.3.0",
  "air_gap_mode": "diode-in",
  "billing_mode": "internal-report-only"
}

{
  "success": true,
  "data": {
    "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customer_id": "{{var:customer_id}}",
    "cluster_name": "Acme QA Sample",
    "k8s_distribution": "openshift",
    "installed_version": "2026.3.0",
    "air_gap_mode": "diode-in",
    "billing_mode": "internal-report-only",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Reads a single on-prem install record by install_id, returning { success: true, data: <install> }. QA edge cases: an unknown install_id is a clean 404 "install not found" because getOnpremInstall() returning null is handled explicitly; the lookup is NOT wrapped in try/catch, so an install_id that fails a Postgres uuid cast (any non-UUID path segment, when the column is a UUID) escapes to the Fastify default 500 body ({ statusCode, error, message }) rather than a 400 or 404 — a common surprise in negative tests; the response is the install row only and does not include its bundles, local LLMs or billing reports, which have their own sub-resources; the route is cross-customer and ops-token gated, so no ownership check is applied to install_id.

[
  "POST /admin/onprem/installs"
]

{
  "install_id": "{{cache:onprem.register-install.response.data.install_id}}"
}

{
  "success": true,
  "data": {
    "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "install not found"
}

Generates a billing report for an on-prem install over the [period_start, period_end] window and records the local artifact path where the report was written, returning 201 { success: true, data: <report> }. Air-gapped installs report billing by producing a local artifact rather than calling home, which is why the path is supplied by the operator. QA edge cases: period_start, period_end and artifact_local_path are all required with a falsy check; the dates are NOT parsed or ordered by the route, so an unparseable timestamp or a period_end before period_start is not a 400 — it either produces an empty report or fails the timestamptz cast as a 500; artifact_local_path is not existence- or writability-checked by the route, so a bad path surfaces as a 500 from the generator; an unknown install_id is an FK violation and therefore a 500, not a 404; regenerating the same period appends another report row rather than replacing.

[
  "POST /admin/onprem/installs"
]

{
  "install_id": "{{cache:onprem.register-install.response.data.install_id}}"
}

{
  "period_start": "2026-04-01",
  "period_end": "2026-06-30",
  "artifact_local_path": "/var/onprem/reports/2026-q2.pdf"
}

{
  "period_start": "2026-04-01",
  "period_end": "2026-06-30",
  "artifact_local_path": "/var/onprem/reports/2026-q2.pdf"
}

{
  "success": true,
  "data": {
    "billing_report_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "period_start": "2026-04-01",
    "period_end": "2026-06-30",
    "artifact_local_path": "/var/onprem/reports/2026-q2.pdf",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Records that a signed release bundle was applied to an on-prem install, capturing bundle_version, whether its signature verified, and the list of migrations applied per SDK; returns 201 { success: true, data: <application record> }. QA edge cases: bundle_version is required and signature_verified must be a real boolean — the guard is typeof !== "boolean", so the strings "true"/"false" and the numbers 1/0 are all rejected as 400, which is the most common false failure when posting from a shell; signature_verified: false is a legitimate accepted value (it records a failed verification) and is NOT rejected; migrations_applied is optional and its [{ sdk, filename }] entries are not shape-validated; an unknown install_id is an FK violation and therefore a 500, not a 404; re-posting the same bundle_version has no conflict branch and may raise a unique violation as a 500.

[
  "POST /admin/onprem/installs"
]

{
  "install_id": "{{cache:onprem.register-install.response.data.install_id}}"
}

{
  "bundle_version": "2026.3.0",
  "signature_verified": true,
  "migrations_applied": [
    {
      "sdk": "sdk-identity",
      "filename": "001_init_identity.sql"
    },
    {
      "sdk": "sdk-onprem",
      "filename": "001_init_onprem.sql"
    }
  ]
}

{
  "bundle_version": "2026.3.0",
  "signature_verified": true,
  "migrations_applied": [
    {
      "sdk": "sdk-identity",
      "filename": "001_init_identity.sql"
    },
    {
      "sdk": "sdk-onprem",
      "filename": "001_init_onprem.sql"
    }
  ]
}

{
  "success": true,
  "data": {
    "bundle_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bundle_version": "2026.3.0",
    "signature_verified": true,
    "migrations_applied": [
      {
        "sdk": "sdk-identity",
        "filename": "001_init_identity.sql"
      },
      {
        "sdk": "sdk-onprem",
        "filename": "001_init_onprem.sql"
      }
    ],
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers a locally hosted LLM against an on-prem install — model id, serving backend (ollama | vllm | text-generation-inference), endpoint URL and quantization (fp16 | int8 | int4 | awq) — returning 201 { success: true, data: <model> }. status is optional (ready | loading | disabled) and defaults inside registerOnpremLocalLlm. QA edge cases: model_id, backend, endpoint_url and quantization are required with a falsy check; backend, quantization and status are typed unions but are NOT runtime-validated by the route, so out-of-enum values only fail at the DB check constraint and return 500 rather than 400; endpoint_url is not URL-validated and is never probed, so registering an unreachable endpoint succeeds; an unknown install_id is an FK violation and therefore a 500, not a 404; re-registering the same model_id on the same install has no conflict branch and may raise a unique violation as a 500.

[
  "POST /admin/onprem/installs"
]

{
  "install_id": "{{cache:onprem.register-install.response.data.install_id}}"
}

{
  "model_id": "llama-3.1-8b-instruct",
  "backend": "vllm",
  "endpoint_url": "http://vllm.onprem.svc.cluster.local:8000/v1",
  "quantization": "int8",
  "status": "loading"
}

{
  "model_id": "llama-3.1-8b-instruct",
  "backend": "vllm",
  "endpoint_url": "http://vllm.onprem.svc.cluster.local:8000/v1",
  "quantization": "int8",
  "status": "loading"
}

{
  "success": true,
  "data": {
    "local_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "model_id": "llama-3.1-8b-instruct",
    "backend": "vllm",
    "endpoint_url": "http://vllm.onprem.svc.cluster.local:8000/v1",
    "quantization": "int8",
    "status": "loading",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Lists every routing pool for the projexcloud-admin /pools page — pool_index, region, isolation_class, status, replication_role, replicates_from_pool_index and timestamps — ordered by region then pool_index, as { success: true, data: rows }. QA edge cases: no filtering, no pagination and no LIMIT, so the whole routing.pool table comes back and response size grows with the fleet; pools in every status (ACTIVE, MIGRATING, DRAINING, MAINTENANCE, RETIRED, QUARANTINE) are returned together with no status filter, so tests expecting only live pools must filter client-side; an empty table is a 200 with data: [], never 404; the route is ops-token gated rather than JWT gated and is fully cross-tenant.

{
  "success": true,
  "data": [
    {
      "pool_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers a routing.pool row (Pool Registry, P1 §8.1) — the create producer for the previously read-only /admin/pools surface, so tests and operators provision pools through the API instead of a SQL fixture. Admin-ops-token gated (x-admin-ops-token, non-JWT). Idempotent on pool_index (ON CONFLICT DO UPDATE). Edge cases: pool_index/pool_family/region/primary_endpoint are required; pool_family must be admin|app|evidence|warehouse|vector; app_id is required only when pool_family='app' (ignored otherwise, per the routing.pool CHECK constraints); status must be a valid pool status; isolation_class is shared|dedicated.

{
  "pool_index": "qa-pool-{{dynamic:slug}}",
  "pool_family": "admin",
  "region": "us-east-1",
  "primary_endpoint": "https://qa-pool.internal",
  "status": "ACTIVE",
  "capacity_tenants": 100,
  "capacity_bytes": 1000000000,
  "isolation_class": "shared"
}

{
  "pool_index": "qa-pool-{{dynamic:slug}}",
  "pool_family": "admin",
  "region": "us-east-1",
  "primary_endpoint": "https://qa-pool.internal",
  "status": "ACTIVE",
  "capacity_tenants": 100,
  "capacity_bytes": 1000000000,
  "isolation_class": "shared"
}

{
  "success": true,
  "data": {
    "pool_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pool_index": "qa-pool-{{dynamic:slug}}",
    "pool_family": "admin",
    "region": "us-east-1",
    "primary_endpoint": "https://qa-pool.internal",
    "status": "ACTIVE",
    "capacity_tenants": 100,
    "capacity_bytes": 1000000000,
    "isolation_class": "shared",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "pool_index": "string",
    "pool_family": "string",
    "region": "string",
    "status": "string",
    "primary_endpoint": "string",
    "isolation_class": "string"
  }
}

Returns one routing pool plus its derived tenant_count and the 25 most recent lifecycle events, as { success: true, data: { pool, tenant_count, lifecycle_history } }. tenant_count counts rows in routing.tenant_pool_map where the pool is the admin or evidence pool, or where the pool_index appears inside app_pool_index — note that last clause is a LIKE substring match, so a short pool_index can over-count by matching longer indexes that contain it. QA edge cases: an unknown pool_index is a clean 404 "pool not found" checked before the count and history queries run; lifecycle_history is capped at 25 rows newest-first with no way to page further back; a pool with no lifecycle events returns an empty array, not a 404; pool_index is a text column so any string is a valid lookup and simply misses rather than erroring.

{
  "pool_index": "{{var:pool_index}}"
}

{
  "success": true,
  "data": {
    "pool_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "pool not found"
}

Transitions a routing pool to a new lifecycle status, recording from_status (read live from routing.pool), to_status, the mandatory reason and operator_id, and broadcasting a pool-flip to route caches. Returns a bare { success: true } with no data. to_status is upper-cased before use, so "draining" and "DRAINING" both work. QA edge cases: to_status, reason and operator_id are all required with a falsy check; the pool is verified to exist first, so an unknown pool_index is a clean 404; there is NO state-machine validation — any status is accepted from any status, including RETIRED → ACTIVE — but a to_status outside ACTIVE|MIGRATING|DRAINING|MAINTENANCE|RETIRED|QUARANTINE is caught only by the DB check constraint and returns 500 rather than 400; re-applying the pool's current status succeeds and still appends a lifecycle event, so the event log is not deduplicated.

{
  "entity": "pool",
  "field": "status",
  "flow": [
    "ACTIVE",
    "MAINTENANCE",
    "DRAINING",
    "RETIRED"
  ],
  "transitions": [
    {
      "from": "ACTIVE",
      "to": "MAINTENANCE",
      "via": "PATCH /admin/pools/:pool_index/status"
    },
    {
      "from": "MAINTENANCE",
      "to": "ACTIVE",
      "via": "PATCH /admin/pools/:pool_index/status"
    },
    {
      "from": "ACTIVE",
      "to": "DRAINING",
      "via": "PATCH /admin/pools/:pool_index/status"
    },
    {
      "from": "DRAINING",
      "to": "RETIRED",
      "via": "PATCH /admin/pools/:pool_index/status"
    }
  ]
}

{
  "pool_index": "{{var:pool_index}}"
}

{
  "to_status": "MAINTENANCE",
  "reason": "Scheduled maintenance window for QA",
  "operator_id": "{{var:operator_id}}"
}

{
  "to_status": "MAINTENANCE",
  "reason": "Scheduled maintenance window for QA",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "statu_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "to_status": "MAINTENANCE",
    "reason": "Scheduled maintenance window for QA",
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Lists admin ops token metadata — id, label, expiry, creation and revocation bookkeeping — and NEVER returns secrets or hashes usable to reconstruct a token, since only SHA-256 hashes are stored. Returns { success: true, data: [...] }. QA edge cases: this is the only way to recover a token's id for revocation, because the plaintext is shown exactly once at mint time; the env ADMIN_OPS_TOKEN break-glass secret is NOT a DB row and therefore never appears in this list, so an empty list does not mean admin access is impossible; the listing has no filtering or pagination and typically includes expired and revoked tokens alongside active ones, so callers must filter on expiry/revocation themselves rather than assuming everything listed still authenticates.

{
  "success": true,
  "data": [
    {
      "ops_token_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": "array"
}

Mints a new DB-backed admin ops token so an operator can grant scoped, optionally time-boxed access (e.g. a short-lived QA token) without rotating the shared env secret or redeploying the gateway. Returns 201 with the issued record — the plaintext token is returned EXACTLY ONCE and only its SHA-256 hash is stored, so it is unrecoverable afterwards. On success the local cache is wiped and a Redis invalidation is broadcast to peer replicas, and a security.admin_ops_token.issued.v1 audit event is emitted. QA edge cases: label is the only required field (trimmed, so whitespace-only is rejected as 400); ttl_seconds is optional and null means a non-expiring token — it is not range-checked, so 0 or a negative value is accepted and yields an already-expired token; the route is itself admin-gated, so minting requires an existing valid token (env break-glass or another DB token); labels are not unique, so duplicate labels are allowed.

{
  "label": "{{dynamic:name}}",
  "ttl_seconds": 3600,
  "reason": "automated qa mint",
  "created_by": "api-test-runner"
}

{
  "label": "Acme QA Sample",
  "ttl_seconds": 3600,
  "reason": "automated qa mint",
  "created_by": "api-test-runner"
}

{
  "success": true,
  "data": {
    "ops_token_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "label": "Acme QA Sample",
    "ttl_seconds": 3600,
    "reason": "automated qa mint",
    "created_by": "api-test-runner",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "id": "string",
    "label": "string",
    "token": "string",
    "expires_at": "string"
  }
}

Revokes a DB-backed admin ops token immediately, returning { success: true, data: { id, status: "revoked" } }. On success it wipes the local token cache, broadcasts a Redis invalidation so peer replicas drop the token too, and emits a security.admin_ops_token.revoked.v1 audit event. QA edge cases: revocation is NOT instantaneous fleet-wide — a replica that misses the Redis broadcast keeps honouring the token until its cache expires (ADMIN_OPS_TOKEN_CACHE_TTL_MS, default 30s), so a negative test immediately after revoking can still see 200s; revoking an unknown id, or one already revoked, returns 404 "token not found or already revoked", making the operation non-idempotent in its status code even though the end state is the same; the env ADMIN_OPS_TOKEN break-glass secret is not a DB row and CANNOT be revoked here — that is deliberate, so operators can never lock themselves out.

[
  "POST /admin/security/ops-tokens"
]

{
  "entity": "ops_token",
  "field": "status",
  "flow": [
    "active",
    "revoked"
  ],
  "transitions": [
    {
      "from": "active",
      "to": "revoked",
      "via": "DELETE /admin/security/ops-tokens/:id"
    }
  ]
}

{
  "id": "{{cache:ops-tokens.create.response.data.id}}"
}

{
  "success": true
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "id": "string",
    "status": "string"
  }
}

P6A emergency rotation of the principal-token signing key, performed immediately rather than on the scheduled interval and always flagged emergency: true. The retired key is kept for a TTL-overlap window so short-lived tokens already in flight stay verifiable, and the rotation emits an audited event. Returns 200 { success: true, data: <rotation result> }. QA edge cases: BOTH body fields are optional with defaults — reason falls back to "manual emergency rotation" and actor_id to "ops-emergency" — so an empty body {} is a valid successful request and there is NO 400 branch on this route at all; whitespace-only values are trimmed to empty and therefore also fall back to the defaults; the call is genuinely state-changing and not idempotent (each invocation rotates again), so repeated calls in a shared environment churn the key and shorten the overlap window for previously issued tokens.

{
  "reason": "QA emergency rotation drill",
  "actor_id": "{{var:operator_id}}"
}

{
  "reason": "QA emergency rotation drill",
  "actor_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "rotate_signing_key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "QA emergency rotation drill",
    "actor_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "rotated_at": "string",
    "fingerprint_current": "string",
    "fingerprint_previous": "string",
    "grace_window_ms": "number",
    "emergency": "boolean"
  }
}

Marks a previously shipped sovereign bundle release as applied in the target region, closing the ship→apply loop, and returns { success: true, data: <release> }. Takes no request body — the release_id path param is the entire input. QA edge cases: an unknown release_id is a clean 404 "release not found" because markSovereignBundleApplied() returning null is handled explicitly; release_id is not format-validated, so arbitrary strings are looked up and simply miss (or fail a uuid cast and become a 500 if the column is a UUID); re-marking an already-applied release depends on whether markSovereignBundleApplied still returns the row — assert the returned status rather than assuming clean idempotency; sending a body is harmless and ignored.

[
  "POST /admin/sovereign/regions",
  "POST /admin/sovereign/regions/:region_id/bundles"
]

{
  "release_id": "{{cache:sovereign.ship-bundle.response.data.release_id}}"
}

{}

{
  "success": true,
  "data": {
    "applied_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Lists every registered sovereign-cloud region (P8 Variant B) as { success: true, data: [...] }, covering all regimes (fedramp-high, il5, pipl, eu-sovereign, uae-trd). Read-only operator surface with no filtering, no pagination and no limit. QA edge cases: listSovereignRegions() is NOT wrapped in try/catch, so a DB failure escapes to the Fastify default error handler and returns the framework 500 body ({ statusCode, error, message }) rather than the { success: false, error } envelope the POST sibling uses — assert the shape accordingly; an empty registry is a 200 with an empty array, never a 404; the route is ops-token gated only, so a valid tenant JWT without x-admin-ops-token is 401.

{
  "success": true,
  "data": [
    {
      "region_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Registers a sovereign-cloud region under a compliance regime with its operator partner and KMS provider, returning 200 { success: true, data: <region> }. terminal_federation is optional and marks a region that may not federate onward. QA edge cases: region_id, regime, operator_partner, kms_provider and operator_id are required by a falsy check (empty strings rejected); regime is typed as fedramp-high|il5|pipl|eu-sovereign|uae-trd but is NOT validated at runtime by the route, so an out-of-enum regime is only caught by the DB check constraint and comes back as a 500 rather than a 400; re-posting an existing region_id has no conflict branch, so it either updates or raises a unique violation as a 500 — never a 409; terminal_federation is optional and defaults inside registerSovereignRegion, so omitting it does not clear a previously set value in a predictable way.

{
  "region_id": "reg-eu-sov-fra",
  "regime": "eu-sovereign",
  "operator_partner": "T-Systems Sovereign Cloud",
  "terminal_federation": true,
  "kms_provider": "aws-cloudhsm-eu-central-1",
  "operator_id": "{{var:operator_id}}"
}

{
  "region_id": "reg-eu-sov-fra",
  "regime": "eu-sovereign",
  "operator_partner": "T-Systems Sovereign Cloud",
  "terminal_federation": true,
  "kms_provider": "aws-cloudhsm-eu-central-1",
  "operator_id": "{{var:operator_id}}"
}

{
  "success": true,
  "data": {
    "region_id": "reg-eu-sov-fra",
    "regime": "eu-sovereign",
    "operator_partner": "T-Systems Sovereign Cloud",
    "terminal_federation": true,
    "kms_provider": "aws-cloudhsm-eu-central-1",
    "operator_id": "{{var:operator_id}}",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Records a compliance attestation for a sovereign region — the regime attested to, the auditor, its validity window and the artifact reference — and returns 201 { success: true, data: <attestation> }. QA edge cases: regime, auditor_id, issued_at, expires_at and artifact_ref are all required with a falsy check; issued_at/expires_at are passed through as strings with NO date parsing or ordering check in the route, so an unparseable timestamp or an expires_at earlier than issued_at is not a 400 — it either lands in the DB as-is or fails the timestamptz cast as a 500; regime is typed but not runtime-validated, so an out-of-enum regime surfaces from the DB check constraint as a 500; an unknown region_id is an FK violation and therefore a 500, not a 404; attestations accumulate — posting twice records two rows rather than replacing.

[
  "POST /admin/sovereign/regions"
]

{
  "entity": "sovereign.region_config",
  "field": "attestation_state",
  "flow": [
    "in-progress",
    "attested",
    "expired"
  ],
  "transitions": [
    {
      "from": "in-progress",
      "to": "attested",
      "via": "POST /admin/sovereign/regions/:region_id/attestations"
    }
  ]
}

{
  "region_id": "{{cache:sovereign.register.response.data.region_id}}"
}

{
  "regime": "eu-sovereign",
  "auditor_id": "{{var:auditor_id}}",
  "issued_at": "{{dynamic:pastdatetime}}",
  "expires_at": "{{dynamic:futuredatetime}}",
  "artifact_ref": "s3://sovereign-attestations/eu-sov-fra-2026Q3.pdf"
}

{
  "regime": "eu-sovereign",
  "auditor_id": "{{var:auditor_id}}",
  "issued_at": "2026-01-15T10:30:00Z",
  "expires_at": "2026-01-15T10:30:00Z",
  "artifact_ref": "s3://sovereign-attestations/eu-sov-fra-2026Q3.pdf"
}

{
  "success": true,
  "data": {
    "attestation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "regime": "eu-sovereign",
    "auditor_id": "{{var:auditor_id}}",
    "issued_at": "2026-01-15T10:30:00Z",
    "expires_at": "2026-01-15T10:30:00Z",
    "artifact_ref": "s3://sovereign-attestations/eu-sov-fra-2026Q3.pdf",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Ships a signed release bundle to a sovereign region, recording the version, the artifact reference and the detached signature, and returns 201 { success: true, data: <release> }. signature_hex is decoded with Buffer.from(hex, "hex") before being handed to shipSovereignBundle. QA edge cases: version, bundle_artifact_ref and signature_hex are all required with a falsy check; signature_hex is NOT validated as hex — Buffer.from silently truncates at the first invalid character and an odd-length or non-hex string yields a short/empty buffer that fails signature verification downstream as a 500, not a 400, so a malformed signature looks like a server error; an unknown region_id in the path is a foreign-key violation surfacing as a 500 rather than a 404; re-shipping the same version has no conflict branch and will typically raise a unique violation as a 500.

[
  "POST /admin/sovereign/regions"
]

{
  "region_id": "{{cache:sovereign.register.response.data.region_id}}"
}

{
  "version": "2026.3.0-{{dynamic:slug}}",
  "bundle_artifact_ref": "oci://registry.projexlight.com/sovereign/eu-sov-fra:2026.3.0",
  "signature_hex": "deadbeefcafef00dba5eba11c0ffee00"
}

{
  "version": "2026.3.0-{{dynamic:slug}}",
  "bundle_artifact_ref": "oci://registry.projexlight.com/sovereign/eu-sov-fra:2026.3.0",
  "signature_hex": "deadbeefcafef00dba5eba11c0ffee00"
}

{
  "success": true,
  "data": {
    "bundle_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version": "2026.3.0-{{dynamic:slug}}",
    "bundle_artifact_ref": "oci://registry.projexlight.com/sovereign/eu-sov-fra:2026.3.0",
    "signature_hex": "deadbeefcafef00dba5eba11c0ffee00",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Ingests a data-sovereignty leak alert for a region — an egress attempt, a cross-region route, or a policy violation — with a severity and an optional incident_ref, returning 201 { success: true, data: <alert> }. QA edge cases: only kind and severity are required (falsy check); incident_ref is optional and explicitly allowed to be null; neither kind nor severity is validated against its enum in the route despite the TypeScript union, so an out-of-enum kind or severity is caught only by the DB check constraint and returns 500 rather than 400; an unknown region_id is an FK violation and therefore a 500, not a 404; every call appends a new alert row — there is no dedup on (region, kind, incident_ref), so replaying the same alert produces duplicates.

[
  "POST /admin/sovereign/regions"
]

{
  "region_id": "{{cache:sovereign.register.response.data.region_id}}"
}

{
  "kind": "egress-attempt",
  "severity": "critical",
  "incident_ref": "INC-2026-0714-eu-sov-fra"
}

{
  "kind": "egress-attempt",
  "severity": "critical",
  "incident_ref": "INC-2026-0714-eu-sov-fra"
}

{
  "success": true,
  "data": {
    "leak_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "kind": "egress-attempt",
    "severity": "critical",
    "incident_ref": "INC-2026-0714-eu-sov-fra",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Forces an immediate out-of-band run of the storm-overlay ingestor instead of waiting for its hourly cadence, walking the provider fallback chain (NOAA → DTN → Weather Underground → synthetic) and upserting storm.event / storm.intensity_cell rows for the trailing window. lookback_hours defaults to 24 and defines the [now - lookback_hours, now] range. QA edge cases: no validation on lookback_hours — a negative value inverts the window (since > until) and simply ingests nothing, a huge value asks the upstream provider for a very wide range and can time out into a 500; the upsert is idempotent so re-running the same window does not duplicate rows; success returns HTTP 200 with { success: true, data: <ingest result> }, and a provider outage is NOT a 4xx because the synthetic provider is the last fallback.

{
  "lookback_hours": 1
}

{
  "lookback_hours": 1
}

{
  "success": true,
  "data": {
    "ingest_now_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "lookback_hours": 1,
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "success": "boolean",
  "data": {
    "events_from": "string",
    "events_ingested": "number",
    "cells_ingested": "number",
    "providers_tried": "array"
  }
}

Operator listing of platform tenants. Returns at most 200 tenants (hard-coded tenantList(200) cap) as { data: { tenants } } — there is no pagination, no cursor and no filtering, so on a platform with more than 200 tenants the tail is silently invisible. QA edge cases: this is a cross-tenant operator surface, so it is gated only by the x-admin-ops-token header and is NOT tenant-scoped by a JWT; a request with a valid tenant JWT but no ops token still gets 401. Extra query params are ignored rather than rejected. Revoking the ops token used here keeps working for up to the 30s admin-ops cache TTL on replicas that did not receive the Redis invalidation broadcast.

{
  "success": true,
  "data": [
    {
      "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "tenants": "array"
  }
}

Provisions a new tenant under an already-existing app and returns 201 { data: { tenant } }. app_id, display_name and region are mandatory; isolation_tier defaults to "S" and module_subscriptions defaults to []. QA edge cases: this is NOT idempotent — calling it twice creates two tenants; app_id must reference a row created by POST /admin/apps first or the tenant_app_id_fkey foreign key fires and the handler translates any error message containing "foreign key" into a 400 ValidationError rather than a 500; empty-string values for the three required fields are falsy and rejected as missing; isolation_tier outside S|P|G is not validated in the handler and reaches the DB check constraint (500); the route is ops-token gated, not JWT gated, so tenant callers cannot self-provision.

[
  "POST /admin/apps"
]

{
  "app_id": "{{cache:apps.create.response.data.app_id}}",
  "display_name": "QA Tenant",
  "region": "us-east-1",
  "isolation_tier": "S",
  "brand_domain": "qa-tenant.example.com",
  "module_subscriptions": [
    "sdk-billing",
    "sdk-analytics"
  ]
}

{
  "app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "display_name": "QA Tenant",
  "region": "us-east-1",
  "isolation_tier": "S",
  "brand_domain": "qa-tenant.example.com",
  "module_subscriptions": [
    "sdk-billing",
    "sdk-analytics"
  ]
}

{
  "success": true,
  "data": {
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "display_name": "QA Tenant",
    "region": "us-east-1",
    "isolation_tier": "S",
    "brand_domain": "qa-tenant.example.com",
    "module_subscriptions": [
      "sdk-billing",
      "sdk-analytics"
    ],
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "tenant": {
      "tenant_id": "string",
      "app_id": "string",
      "display_name": "string",
      "region": "string",
      "isolation_tier": "string",
      "status": "string"
    }
  }
}

Creates/updates a routing.tenant_pool_map row assigning a tenant to pools (P1 §8.1) — producer for the tenant->pool mapping so GET /api/router/resolve resolves without a SQL fixture. Admin-ops-token gated. Idempotent on tenant_id (ON CONFLICT DO UPDATE). admin_pool_index (and evidence_pool_index, if set) must reference an existing routing.pool (a bad FK returns 400, not 500). app_pool_index is a jsonb map of app_id->pool_index. Edge cases: :tenant_id must be a UUID; admin_pool_index + region are required; status ACTIVE|MIGRATING|QUARANTINED.

[
  "POST /api/auth/signup-tenant",
  "POST /admin/pools"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "admin_pool_index": "{{cache:admin.pools.create.response.data.pool_index}}",
  "app_pool_index": {},
  "region": "us-east-1",
  "status": "ACTIVE"
}

{
  "admin_pool_index": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "app_pool_index": {},
  "region": "us-east-1",
  "status": "ACTIVE"
}

{
  "success": true,
  "data": {
    "pool_map_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "admin_pool_index": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "app_pool_index": {},
    "region": "us-east-1",
    "status": "ACTIVE",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "tenant_id": "string",
    "admin_pool_index": "string",
    "region": "string",
    "status": "string"
  }
}

Operator cross-tenant listing of webhook endpoints — endpoint_id, tenant_id, url, status, failure_streak, last_success_at, last_failure_at, created_at — newest-first and capped at 200 rows, with an optional tenant_id query filter. QA edge cases: omitting tenant_id returns endpoints across ALL tenants, which is the point of this route; the 200-row cap has no pagination or cursor, so the tail is invisible on a busy platform; a tenant_id that is not a valid UUID fails the ::uuid cast and returns 500 with the raw driver message rather than a 400; a tenant_id that is valid but unknown is a 200 with an empty array, never 404; disabled and healthy endpoints are returned together with no status filter, and failure_streak is the field to watch for endpoints heading toward the DLQ.

{
  "success": true,
  "data": [
    {
      "webhook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Operator cross-tenant dead-letter queue view: deliveries in status "dlq" whose dlq_until is NULL or still in the future, joined to their subscription and endpoint to expose delivery_id, endpoint_id, event_type, attempts, failed_at and tenant_id. Ordered by last_attempt_at descending (NULLS LAST) and capped at 100 rows. QA edge cases: entries whose dlq_until has already passed are filtered OUT of this list — a delivery can therefore vanish from the DLQ view purely by aging, and replaying it afterwards returns 409 from the replay route, so QA should read this list and replay promptly; the query is deliberately not tenant-filtered, so it spans all tenants; the 100-row cap has no pagination; an empty DLQ is a 200 with data: [], never a 404.

{
  "success": true,
  "data": [
    {
      "dlq_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Re-enqueues a dead-lettered webhook delivery for another attempt, returning { success: true, data: <replay result> }. Takes no request body — the delivery_id path param is the whole input. QA edge cases: two distinct typed failures are mapped explicitly — DeliveryNotInDlqError becomes 404 (the delivery does not exist, or exists but is not in dlq status, so a successfully delivered id also 404s) and DlqWindowExpiredError becomes 409 (the delivery is in the DLQ but its dlq_until retention window has passed, making it permanently unreplayable). That 409 is the key edge case: an entry can be visible in GET /admin/webhooks/dlq at one moment and 409 shortly after, since the list filters on the same dlq_until. Replay is not idempotent — a successful replay moves the delivery out of dlq, so an immediate second call returns 404.

{
  "entity": "webhook.delivery",
  "field": "status",
  "flow": [
    "pending",
    "dlq",
    "pending"
  ],
  "transitions": [
    {
      "from": "dlq",
      "to": "pending",
      "via": "POST /admin/webhooks/dlq/:delivery_id/replay"
    }
  ]
}

{
  "delivery_id": "{{var:dlq_delivery_id}}"
}

{}

{
  "success": true,
  "data": {
    "status": "completed",
    "replay_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Operator-triggered sensor rollup backfill (P12·E1) that recomputes the 1-minute and 1-hour ClickHouse rollups for a trailing window, off the hot path. The window is [from, to]; when omitted, to defaults to now and from to now - lookback_hours (default 24). The recompute is delete-then-reinsert, so it is idempotent and safe to re-run over the same range. QA edge cases: the route hard-requires ClickHouse — with config.clickhouse.enabled false every authenticated call returns 409 before any work happens, which is the single most common false failure in a Postgres-only test environment; from/to are passed to new Date() with no validation, so an unparseable string yields "Invalid Date" and surfaces as a 500 from the query rather than a 400; from later than to produces an empty window and a zero-count success; very wide windows are not capped and can exhaust the ClickHouse container.

{
  "lookback_hours": 24,
  "from": "{{dynamic:pastdatetime}}",
  "to": "{{dynamic:futuredatetime}}"
}

{
  "lookback_hours": 24,
  "from": "2026-01-15T10:30:00Z",
  "to": "2026-01-15T10:30:00Z"
}

{
  "success": true,
  "data": {
    "backfill_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "lookback_hours": 24,
    "from": "2026-01-15T10:30:00Z",
    "to": "2026-01-15T10:30:00Z",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

Liveness probe for the api-gateway. Returns 200 {status:'ok', service:<config.appName>, timestamp:<ISO 8601>} from a handler that only reads process config and the clock — it performs no database, Redis or ClickHouse check, so it stays 200 even when a downstream dependency is degraded (it is a liveness, not a readiness, signal). QA edge cases: '/health' is on the authGate.ts PUBLIC_EXACT allowlist (and the isHealth() suffix rule additionally exempts every '*/health' path), so it is intentionally unauthenticated — sending no token, a garbage token or an expired token all still return 200, and asserting a 401 here would be wrong. There are no path params, query params or body, and unknown query strings are ignored rather than rejected, so there is no 400 branch; the response is fully idempotent apart from `timestamp`, which advances on every call. Only GET is routed — other verbs fall through to Fastify's default 404 for the method/URL pair. Not tenant-scoped and not paginated. The handler contains no throw and no reply.code() other than the implicit 200, so it has no client-error surface at all.

{
  "success": true,
  "data": [
    {
      "health_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

List the tenant's call legs, newest first, optionally filtered by status, direction, or is_voicemail. is_voicemail=true isolates the calls that answering-machine detection classified as reaching voicemail rather than a person. Edge cases: 400 when the tenant_id query param is missing; a tenant with no calls returns an empty array rather than 404; is_voicemail is only applied when the param is present (absent means 'either'), and any value other than the literal 'true' reads as false; limit defaults to 50 and offset to 0.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers",
  "POST /api/voice/calls"
]

{
  "success": true,
  "data": [
    {
      "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "calls": [
      {
        "voice_call_id": "string",
        "external_id": "string",
        "status": "string"
      }
    ]
  }
}

Place an outbound call. The request always sets a statusCallback URL and, by default, requests recording plus answering-machine detection (AMD) — recording because the SOP requires it, AMD because it is what lets the status webhook tell a human answer from a voicemail. RECORDING CONSENT GATE (TK-3654): when record is requested the call is checked against sdk-consent FIRST, and recording is withheld AT SOURCE — Twilio is never asked to record — unless there is an affirmative grant. Denial and the absence of any decision both withhold (recording_withheld_reason = consent_denied / consent_unknown), so an unconfigured environment never silently records anyone; the decision is persisted on the row as recording_consent (true/false/null) with its receipt id. Response field payload.record therefore reflects what was ACTUALLY requested upstream, which may be false even when the caller sent record:true. A mirror row is written in status 'queued' before Twilio's callbacks begin arriving; the status/recording webhooks then complete it. Caller-id resolution order: explicit from_number, else the referenced tracking_number_id (must be active), else the tenant's most recently provisioned ACTIVE tracking number. Edge cases: 400 NoCallerIdAvailable when none of those resolve — the call is rejected rather than dialled from an arbitrary number; 400 when tenant_id, install_id or to_number is missing; 422 with remediation when the upstream call request fails; repeat callbacks for the same Call SID are idempotent via UNIQUE(install_id, external_id).

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "install_id": "{{dynamic:uuid}}",
  "to_number": "+14155550123",
  "from_number": "+14155550100",
  "tracking_number_id": "{{cache:voice.tracking-numbers.create.response.data.tracking_number.tracking_number_id}}",
  "subject_persona_id": "{{cache:auth.signup-tenant.response.data.userId}}",
  "initiated_by_persona_id": "{{cache:auth.signup-tenant.response.data.userId}}",
  "record": true,
  "machine_detection": true,
  "metadata": {
    "campaign": "google-ads-q3"
  }
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "to_number": "+14155550123",
  "from_number": "+14155550100",
  "tracking_number_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "subject_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "initiated_by_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "record": true,
  "machine_detection": true,
  "metadata": {
    "campaign": "google-ads-q3"
  }
}

{
  "success": true,
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "to_number": "+14155550123",
    "from_number": "+14155550100",
    "tracking_number_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subject_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "initiated_by_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "record": true,
    "machine_detection": true,
    "metadata": {
      "campaign": "google-ads-q3"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "call": {
      "voice_call_id": "string",
      "external_id": "string",
      "status": "string",
      "from_number": "string",
      "to_number": "string"
    }
  }
}

Fetch a single call leg by id, including its recording fields, AMD outcome (answered_by), is_voicemail classification and any voicemail transcript. Tenant-scoped: another tenant's call reads as not-found rather than leaking its existence. Edge cases: 400 when the tenant_id query param is missing; 404 for an unknown id or one belonging to a different tenant; recording_url/recording_sid stay null until the recording webhook delivers them, and answered_by stays null until the status callback carrying AMD arrives.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers",
  "POST /api/voice/calls"
]

{
  "voice_call_id": "{{cache:voice.calls.create.response.data.call.voice_call_id}}"
}

{
  "success": true,
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "call": {
      "voice_call_id": "string",
      "external_id": "string",
      "status": "string",
      "is_voicemail": "boolean"
    }
  }
}

List the tenant's Twilio tracking numbers, newest first, optionally filtered by status. Released numbers are retained and still listed (filter status=active to exclude them) so historical call attribution survives a release. Edge cases: 400 when the tenant_id query param is missing; a tenant with no numbers returns an empty array rather than 404; limit defaults to 50 and offset to 0.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers"
]

{
  "success": true,
  "data": [
    {
      "tracking_number_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "tracking_numbers": [
      {
        "tracking_number_id": "string",
        "phone_number": "string",
        "status": "string"
      }
    ]
  }
}

Provision a Twilio tracking number and pin it to the tenant so inbound calls can be attributed to the campaign/source that owns the number. The upstream purchase goes through a pluggable provider (setTwilioVoiceProvider); when no live Twilio client is injected the built-in stub mints a synthetic SID and E.164 number, so this endpoint works without Twilio credentials. Supply phone_number to claim a specific number, or area_code to let the provider pick one. Edge cases: re-provisioning the SAME upstream SID for the same install is idempotent via UNIQUE(install_id, external_id) and returns the existing row (friendly_name/purpose/assigned_persona_id are refreshed); a DIFFERENT SID resolving to a number the tenant already holds ACTIVE returns 409, because a partial unique index allows only one active claim per (tenant, phone_number); released rows are retained so historical calls stay attributable; 400 when tenant_id or install_id is missing; 422 with a remediation hint when the upstream provisioning call fails.

[
  "POST /api/auth/signup-tenant"
]

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "install_id": "{{dynamic:uuid}}",
  "friendly_name": "Inbound campaign line",
  "purpose": "google-ads-q3",
  "area_code": "415",
  "assigned_persona_id": "{{cache:auth.signup-tenant.response.data.userId}}"
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "friendly_name": "Inbound campaign line",
  "purpose": "google-ads-q3",
  "area_code": "415",
  "assigned_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "success": true,
  "data": {
    "tracking_number_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "install_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "friendly_name": "Inbound campaign line",
    "purpose": "google-ads-q3",
    "area_code": "415",
    "assigned_persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "tracking_number": {
      "tracking_number_id": "string",
      "phone_number": "string",
      "external_id": "string",
      "status": "string"
    }
  }
}

Release a tracking number back to Twilio and mark the mirror row 'released' with released_at stamped. The row is deliberately KEPT rather than deleted so historical calls placed from that number stay attributable, and releasing frees the (tenant, phone_number) active-claim slot so the number can be re-provisioned later. Edge cases: releasing an ALREADY-released number is an idempotent no-op that returns the current row (not a 409); 400 when tenant_id is missing from the body; 404 when the id is unknown or belongs to another tenant; 422 with remediation when the upstream release fails — retry reconciles the mirror if the number was already released in the Twilio console. After release the tenant may have no active number, in which case a later POST /api/voice/calls without an explicit from_number returns 400 NoCallerIdAvailable.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers",
  "POST /api/voice/calls"
]

{
  "tracking_number_id": "{{cache:voice.tracking-numbers.create.response.data.tracking_number.tracking_number_id}}"
}

{
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "success": true,
  "data": {
    "release_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "data": {
    "tracking_number": {
      "tracking_number_id": "string",
      "status": "string",
      "released_at": "string"
    }
  }
}

PUBLIC signed webhook: Twilio posts here once a call recording is ready, carrying RecordingSid, RecordingUrl and RecordingDuration. Authentication is by X-Twilio-Signature exactly as for the status callback (fail-closed once TWILIO_AUTH_TOKEN is set, permissive when unconfigured so local/test runs work unsigned); the gateway allowlists the /api/voice/webhooks/ prefix past the default-deny authGate. CONSENT GATE (TK-3654): recording_url is the pointer to the actual audio, so it is stored ONLY when the call carries an affirmative sdk-consent grant. A denial AND the absence of any decision both withhold it and stamp recording_withheld_reason (consent_denied / consent_unknown) — 'no recording stored without a consent decision' means missing consent must fail closed. RecordingSid and RecordingDuration ARE retained even when withheld: knowing a recording exists upstream is what makes a later deletion request actionable, and that metadata is not itself the recording. With no consent seeded (the default in a fresh environment) the happy path therefore returns recording_stored=false and recording_withheld_reason='consent_unknown'. Other edge cases: recording fields merge with COALESCE so re-delivery is idempotent and a callback missing a field never nulls a stored value; an unrecognised or absent CallSid is acknowledged with 202 rather than 404 so Twilio stops retrying; recordings normally arrive AFTER the call completed and do not alter call status; 401 InvalidSignature only when a configured signature fails to verify.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers",
  "POST /api/voice/calls"
]

{
  "CallSid": "{{cache:voice.calls.create.response.data.call.external_id}}",
  "RecordingSid": "RE{{dynamic:slug}}",
  "RecordingUrl": "https://api.twilio.com/2010-04-01/Recordings/RE{{dynamic:slug}}",
  "RecordingDuration": "40"
}

{
  "CallSid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "RecordingSid": "RE{{dynamic:slug}}",
  "RecordingUrl": "https://api.twilio.com/2010-04-01/Recordings/RE{{dynamic:slug}}",
  "RecordingDuration": "40"
}

{
  "success": true,
  "data": {
    "recording_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CallSid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "RecordingSid": "RE{{dynamic:slug}}",
    "RecordingUrl": "https://api.twilio.com/2010-04-01/Recordings/RE{{dynamic:slug}}",
    "RecordingDuration": "40",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "matched": "boolean",
    "voice_call_id": "string",
    "recording_sid": "string",
    "recording_duration_seconds": "number",
    "recording_stored": "boolean",
    "recording_withheld_reason": "string"
  }
}

PUBLIC signed webhook: Twilio posts call-progress here (queued -> initiated -> ringing -> in-progress -> completed, or a terminal busy/no-answer/canceled/failed). Authentication is by X-Twilio-Signature (HMAC-SHA1 over the request URL plus every parameter appended as key+value in sorted order, base64), NOT a tenant JWT — so the gateway's default-deny authGate allowlists the /api/voice/webhooks/ prefix. Verification is fail-closed once TWILIO_AUTH_TOKEN is configured and permissive when it is not, so local and test runs work unsigned. AnsweredBy carries answering-machine detection: machine_start / machine_end_* mark the call is_voicemail, while 'unknown' and 'fax' deliberately do NOT (unknown means detection was inconclusive and treating it as voicemail would log phantom voicemails). Edge cases: callbacks are RETRIED and can arrive OUT OF ORDER, so a status is never allowed to regress out of a terminal state and is_voicemail is sticky once set; an unrecognised CallSid is acknowledged with 202 rather than 404, because retrying would never make the call known; a missing CallSid is likewise 202; 401 InvalidSignature only when a token is configured and the signature is absent/wrong/over tampered params.

[
  "POST /api/auth/signup-tenant",
  "POST /api/voice/tracking-numbers",
  "POST /api/voice/calls"
]

{
  "CallSid": "{{cache:voice.calls.create.response.data.call.external_id}}",
  "CallStatus": "completed",
  "AnsweredBy": "machine_start",
  "CallDuration": "42",
  "ErrorCode": ""
}

{
  "CallSid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "CallStatus": "completed",
  "AnsweredBy": "machine_start",
  "CallDuration": "42",
  "ErrorCode": ""
}

{
  "success": true,
  "data": {
    "statu_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CallSid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CallStatus": "completed",
    "AnsweredBy": "machine_start",
    "CallDuration": "42",
    "ErrorCode": "",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "data": {
    "matched": "boolean",
    "voice_call_id": "string",
    "status": "string",
    "is_voicemail": "boolean",
    "voicemail_detected": "boolean"
  }
}

G-1 contracts-only task: adds 27 P6A event types to EVENT_TYPE_REGISTRY in @projexlight/contracts plus cross-SDK types (AgentContext, CompletionRequest/Response, StreamChunk, CapabilityToken, ExecutionLogEntry, ToolManifest, TraceSpan/Timeline, MCP types). No HTTP surface — the 'endpoint' is a synthetic in-process registry mutation. Enforcement is the existing assertRegisteredEventType() guard plus the producer-side schema validator (OC-2 doctrine).

{
  "success": true,
  "data": {
    "p6a_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "success": true
}

G-1 contracts-only task: adds 27 P6B event types to EVENT_TYPE_REGISTRY in @projexlight/contracts plus cross-SDK types (RagCorpus/Hit/Retrieval, ParseJob/Stage/ExtractedField, ConversationSession/Turn/Handoff, RecommendationModel/Suggestion/Feedback, RollupSpec/QueryResult/IcebergTableRef, LineageNode/Edge/Chain (G8), Ontology/SemanticObject/Relation/CapabilityGraph/Intent/Plan/Policy/Bridge (G9, 6 types), Snowflake Install/Binding/SyncRun/Query). No HTTP surface — the 'endpoint' is a synthetic in-process registry mutation. Enforcement is the existing assertRegisteredEventType() guard plus the producer-side schema validator (OC-2 doctrine).

{
  "success": true,
  "data": {
    "p6b_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "success": true
}

Returns the hdk-camera native capability manifest — supported photo formats (jpeg/heic/raw_dng), video codecs (h264/hevc/av1), max photo (48MP) and video (4K@60) resolution, flash/depth-sensor/OCR-passthrough flags, and the iOS/Android native module names the JS bridge must load. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "capability_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the four hdk-camera video recording presets (standard 1080p30 h264, high 4K30 hevc, slow-mo 1080p240 h264, time-lapse 4K 1fps hevc) so the client can offer a preset picker without hard-coding resolutions. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "recording_preset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Drains the persistent hdk-diagnostic outbox: claims up to `limit` rows from hdk_diagnostic.event where drained_at IS NULL (oldest received_at first, FOR UPDATE SKIP LOCKED), stamps drained_at = now(), and returns the claimed rows plus their count with 200. The body is optional - an absent body or absent `limit` defaults to 1000. Edge cases: draining an empty outbox returns 200 with events: [] and count: 0, never 404; the drain is destructive and NOT idempotent - an immediate second call returns the next batch rather than the same one, because the first call already stamped drained_at; concurrent callers never receive overlapping rows (SKIP LOCKED); a non-numeric or negative `limit` is passed straight into SQL LIMIT and fails at the database rather than in a validation branch; there is no tenant scoping on this route, so it drains the outbox across all devices and tenants.

[
  "POST /api/auth/register"
]

{
  "limit": 50
}

{
  "limit": 50
}

{
  "success": true,
  "data": {
    "drain_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "limit": 50,
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Captures a single device diagnostic event into the persistent hdk_diagnostic.event outbox (device_uuid, category, JSONB payload, occurred_at) and returns 202 with the generated event_id; a downstream drain worker later ships it to long-term storage. device_uuid and category are required; payload defaults to {} and occurred_at defaults to now() when omitted. Edge cases: an empty-string device_uuid or category is rejected by the falsy missing-fields check; duplicate submissions are NOT deduplicated - each call inserts a new row with a fresh event_id, so client retries create duplicates; an unparseable occurred_at becomes an Invalid Date and fails at the INSERT rather than in validation; payload is stringified into jsonb so oversized payloads are bounded only by the Fastify body limit; there is no FK on device_uuid and no tenant scoping, so events for an unknown device are accepted.

[
  "POST /api/auth/register"
]

{
  "device_uuid": "{{static:test-device-uuid-001}}",
  "category": "battery",
  "payload": {
    "level": 0.42,
    "charging": false
  },
  "occurred_at": "{{dynamic:pastdatetime}}"
}

{
  "device_uuid": "test-device-uuid-001",
  "category": "battery",
  "payload": {
    "level": 0.42,
    "charging": false
  },
  "occurred_at": "2026-01-15T10:30:00Z"
}

{
  "success": true,
  "data": {
    "status": "accepted",
    "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Registers (upserts) a device identity claim binding a device_uuid to a person_id, optionally storing a biometric template envelope and/or PIN envelope (base64 blobs). Requires device_uuid and person_id; envelopes are optional (a claim with neither credential is accepted). Idempotent upsert on (device_uuid, person_id): a repeat call COALESCE-updates envelopes (a null envelope does NOT overwrite an existing one) and returns 201 — no duplicate/conflict error. Edge cases: empty-string vs missing fields, non-base64 envelopes, repeat registrations.

[
  "POST /api/auth/register",
  "POST /scim/v2/Users"
]

{
  "device_uuid": "device-hdk-idp-e2e-001",
  "person_id": "{{cache:scim.create.response.data.person_id}}",
  "biometric_template_envelope": "dGVzdC1iaW9tZXRyaWMtdGVtcGxhdGU=",
  "pin_envelope": "dGVzdC1waW4tZW52ZWxvcGU="
}

{
  "device_uuid": "device-hdk-idp-e2e-001",
  "person_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "biometric_template_envelope": "dGVzdC1iaW9tZXRyaWMtdGVtcGxhdGU=",
  "pin_envelope": "dGVzdC1waW4tZW52ZWxvcGU="
}

{
  "success": true,
  "data": {
    "claim_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "device_uuid": "device-hdk-idp-e2e-001",
    "person_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "biometric_template_envelope": "dGVzdC1iaW9tZXRyaWMtdGVtcGxhdGU=",
    "pin_envelope": "dGVzdC1waW4tZW52ZWxvcGU=",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Lists every device identity claim registered for one device_uuid, returning claim_id, device_uuid, person_id, the biometric_template_envelope and pin_envelope blobs, last_used_at and created_at. A device may carry several claims, one per bound person. Edge cases: an unknown or never-registered device_uuid returns 200 with claims: [] and never 404; device_uuid is a TEXT column, so any string including a non-UUID is a legal lookup key that simply matches nothing (no cast error); the result set is unpaginated and unordered, so a device with many bound persons returns every row in whatever order Postgres yields; the query filters on device_uuid alone with no tenant or persona predicate, so the caller's JWT tenant does not narrow the results.

[
  "POST /api/auth/register",
  "POST /api/hdk-idp/claims"
]

{
  "device_uuid": "{{cache:claims.register.response.data.claim.device_uuid}}"
}

{
  "success": true,
  "data": {
    "claim_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Records an authentication a device performed while offline, writing it to hdk_idp.offline_auth_log on the next sync and touching last_used_at on the matching (device_uuid, person_id) device_claim. All four fields - device_uuid, person_id, method and occurred_at - are required, and method must be one of biometric, pin or passkey (also enforced by a CHECK constraint on the table). Edge cases: an unrecognised method has its own distinct 400 branch separate from the missing-fields branch; there is no FK and no uniqueness constraint, so an unknown device/person is accepted and replaying the same event inserts a duplicate log row (not idempotent); when no claim matches, the last_used_at UPDATE affects zero rows silently and the call still returns 201; person_id must be a UUID and occurred_at must be a parseable timestamp - both are handled at the database and fail there, not in a validation branch.

[
  "POST /api/auth/register",
  "POST /api/hdk-idp/claims"
]

{
  "device_uuid": "{{cache:claims.register.response.data.claim.device_uuid}}",
  "person_id": "{{cache:claims.register.response.data.claim.person_id}}",
  "method": "biometric",
  "occurred_at": "{{dynamic:pastdatetime}}"
}

{
  "device_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "person_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "method": "biometric",
  "occurred_at": "2026-01-15T10:30:00Z"
}

{
  "success": true,
  "data": {
    "log_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "device_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "person_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "method": "biometric",
    "occurred_at": "2026-01-15T10:30:00Z",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the hdk-image-editor capability manifest — available tools (crop/rotate/flip/markup/text/blur/sharpen/filter), the five named filters, supported output formats (jpeg/png/heic), and the iOS/Android native module names. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "capability_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the hdk-map capability manifest — supported overlay types (pin/polyline/polygon/heatmap/cluster), gestures, offline-caching and geofencing flags, routing modes (driving/walking/cycling/transit), and the iOS/Android native module names. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "capability_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the four configured map tile providers (mapbox-streets, mapbox-satellite, apple-standard, osm) with their {z}/{x}/{y} URL patterns and a requires_token flag. Security-relevant assertion for QA: this endpoint must NEVER return an actual tile access token — clients fetch those separately via sdk-secrets, so a response containing a token-like value is a defect. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "tile_provider_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Lists every measurement recorded for one capture, filtered by the required capture_id query param and returned as { success: true, data: [...] }. QA edge cases: omitting capture_id is a 400, but an unknown or non-existent capture_id is NOT — it returns 200 with an empty array, so "no such capture" and "capture with zero measurements" are indistinguishable; there is no limit/offset parameter, so the endpoint returns the full unpaginated set for a capture; there is no tenant scoping on the query, so results are keyed purely by capture_id.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant",
  "POST /api/hdk/measure"
]

{
  "success": true,
  "data": [
    {
      "measure_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Records one HDK device measurement (area / distance / volume) against a capture and persists it to hdk_measure.measurement. The route validates capture_id, kind, value, unit and device_uuid at the edge, then measurementService re-validates and inserts, returning 201 with the stored row. QA edge cases: EVERY validation failure — route-level missing field, unknown kind, non-finite or negative value, a captured_at that is not valid ISO 8601, or a database insert failure — collapses to HTTP 400, so assert on the error string, not just the status; value === 0 is accepted (only negative is rejected) while value omitted entirely is rejected, so a 0-value test must not be treated as a missing-field test; tenant_id is optional and defaults to null, meaning this endpoint does NOT enforce tenant scoping on write; the call is not idempotent — POSTing the same body twice creates two rows with different ids; the route has no requireAuth preHandler of its own but is still covered by the gateway default-deny authGate, so an anonymous call returns 401 before reaching the handler.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant"
]

{
  "capture_id": "{{var:capture_id}}",
  "kind": "distance",
  "value": 3.5,
  "unit": "m",
  "accuracy_class": "high",
  "device_uuid": "{{dynamic:uuid}}",
  "captured_at": "{{dynamic:pastdatetime}}",
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "capture_id": "{{var:capture_id}}",
  "kind": "distance",
  "value": 3.5,
  "unit": "m",
  "accuracy_class": "high",
  "device_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "captured_at": "2026-01-15T10:30:00Z",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "success": true,
  "data": {
    "measure_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "capture_id": "{{var:capture_id}}",
    "kind": "distance",
    "value": 3.5,
    "unit": "m",
    "accuracy_class": "high",
    "device_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "captured_at": "2026-01-15T10:30:00Z",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Fetches a single measurement from hdk_measure.measurement by its measurement id and returns it as { success: true, data }. QA edge cases: an id that does not exist returns 404 with error "not found" — the same 404 is returned for a well-formed-but-unknown UUID and for a syntactically invalid id, so a malformed-id test cannot be distinguished from a missing-record test by status alone; there is no tenant filter on the lookup, so any authenticated caller who knows an id can read that row (do not assert cross-tenant isolation here); the read is idempotent and safe to repeat.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant",
  "POST /api/hdk/measure"
]

{
  "id": "{{cache:measure.create.response.data.measurement_id}}"
}

{
  "success": true,
  "data": {
    "measure_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the most recent permission-surface snapshot captured for a device - the newest hdk_permissions.surface_snapshot row for that device_uuid by taken_at DESC - including snapshot_id, tenant_id, persona_id, the permission_set JSONB and taken_at. Edge cases: unlike the sibling claims list, a device with no snapshot yet returns 404 NotFound rather than an empty payload, so this must be exercised after a POST /api/hdk-permissions/snapshots for the same device_uuid; device_uuid is a TEXT column, so any non-matching string including a non-UUID yields a clean 404 rather than a cast error; only one row is ever returned no matter how many snapshots exist, and ties on taken_at are broken arbitrarily; the lookup is keyed solely on device_uuid - the row's tenant_id is returned but is never checked against the caller's JWT tenant.

[
  "POST /api/auth/signup-tenant",
  "POST /api/hdk-permissions/snapshots"
]

{
  "device_uuid": "{{cache:hdk-permissions.snapshot.response.data.snapshot.device_uuid}}"
}

{
  "success": true,
  "data": {
    "latest_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Captures the current permission-surface state of a device: the permission_set map (permission name to boolean or string, stored as JSONB) for a device_uuid within a tenant, optionally scoped to a persona_id, returning 201 with the stored snapshot including its generated snapshot_id and taken_at. device_uuid, tenant_id and permission_set are required; persona_id is optional and stored as NULL when omitted. Edge cases: there is no uniqueness constraint, so every call appends a new historical row - repeat posts are intentionally NOT idempotent and build the timeline that GET /devices/:device_uuid/latest reads; an empty permission_set object {} passes the presence check and is accepted, while a missing key is rejected; tenant_id and persona_id must be valid UUIDs and are enforced by the column types, not by handler validation; tenant_id comes from the body and is never cross-checked against the caller's JWT tenant.

[
  "POST /api/auth/signup-tenant"
]

{
  "device_uuid": "test-device-uuid-001",
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "persona_id": "{{var:persona_id}}",
  "permission_set": {
    "camera": true,
    "location": "when-in-use"
  }
}

{
  "device_uuid": "test-device-uuid-001",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "persona_id": "{{var:persona_id}}",
  "permission_set": {
    "camera": true,
    "location": "when-in-use"
  }
}

{
  "success": true,
  "data": {
    "snapshot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "device_uuid": "test-device-uuid-001",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "persona_id": "{{var:persona_id}}",
    "permission_set": {
      "camera": true,
      "location": "when-in-use"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the hdk-scanner capability manifest — supported barcode symbologies (qr_code, pdf_417, code_128, ean_13, data_matrix), document-detection and OCR flags, and the iOS/Android native module names, so JS can negotiate scanner availability without calling into native code. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "capability_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Resolves a two-sided conflict for an event_type by applying that type's registered policy (crdt / lww / merge / event-sourcing / human-review) to input_a and input_b, optionally linking the outcome to a batch_id and an audit_entry_id. Edge cases: the event_type MUST already be registered via PUT /api/hdk-sync/event-type-policies — an unregistered type returns 409 UnregisteredEventType, not 404; input_a and input_b must both be present objects (a falsy or missing side is a 400); the catch block maps ANY resolver throw to 409, so unrelated resolver failures also present as UnregisteredEventType; a 'human-review' policy does not resolve inline, it enqueues a human-review task; batch_id and audit_entry_id are optional linkage only.

[
  "POST /api/auth/register",
  "PUT /api/hdk-sync/event-type-policies"
]

{
  "event_type": "{{cache:hdk-sync.event-type-policies.create.response.data.policy.event_type}}",
  "input_a": {
    "ops": [
      {
        "position": 0,
        "char": "A",
        "ts": 1,
        "replica_id": "d1"
      }
    ]
  },
  "input_b": {
    "ops": [
      {
        "position": 0,
        "char": "B",
        "ts": 2,
        "replica_id": "d2"
      }
    ]
  }
}

{
  "event_type": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "input_a": {
    "ops": [
      {
        "position": 0,
        "char": "A",
        "ts": 1,
        "replica_id": "d1"
      }
    ]
  },
  "input_b": {
    "ops": [
      {
        "position": 0,
        "char": "B",
        "ts": 2,
        "replica_id": "d2"
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "status": "completed",
    "event_type": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "input_a": {
      "ops": [
        {
          "position": 0,
          "char": "A",
          "ts": 1,
          "replica_id": "d1"
        }
      ]
    },
    "input_b": {
      "ops": [
        {
          "position": 0,
          "char": "B",
          "ts": 2,
          "replica_id": "d2"
        }
      ]
    },
    "resolve_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Lists every registered event-type conflict policy. Takes no query parameters — there is no paging, filtering or tenant scoping, so the full registry is returned on each call and an empty registry yields data.policies = [] with 200, not 404. Read-only and safe to poll; clients use it to learn which event types may be replayed before starting a batch.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "event_type_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Registers (upserts) the conflict-resolution policy for a sync event_type: which of crdt | lww | merge | event-sourcing | human-review applies when two device replays disagree, plus an optional free-text strategy_detail and a retention_class. Idempotent — re-PUTting the same event_type overwrites the policy and returns 200 (never 201), so it is safe to replay. Edge cases: an unknown conflict_policy or retention_class is rejected 400 by an explicit whitelist in the route; an empty-string event_type is treated as missing; strategy_detail and retention_class are optional; the registry is global (not tenant-scoped), so a policy registered by one tenant's operator governs every tenant's replays for that event_type.

[
  "POST /api/auth/register"
]

{
  "event_type": "clinical.note.edit.v1",
  "conflict_policy": "human-review",
  "strategy_detail": "human-review:dual-control",
  "retention_class": "regulated"
}

{
  "event_type": "clinical.note.edit.v1",
  "conflict_policy": "human-review",
  "strategy_detail": "human-review:dual-control",
  "retention_class": "regulated"
}

{
  "success": true,
  "data": {
    "event_type_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "event_type": "clinical.note.edit.v1",
    "conflict_policy": "human-review",
    "strategy_detail": "human-review:dual-control",
    "retention_class": "regulated",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Fetches the conflict policy registered for a single event_type given as a path segment. Edge cases: the lookup is an exact, case-sensitive match on the event_type string, so a differently-cased or escaped value that does not decode to the exact registered string returns 404; an unregistered event_type also returns 404 (the route never lazily creates a policy). Global registry — no tenant scoping.

[
  "POST /api/auth/register",
  "PUT /api/hdk-sync/event-type-policies"
]

{
  "event_type": "{{cache:hdk-sync.event-type-policies.create.response.data.policy.event_type}}"
}

{
  "success": true,
  "data": {
    "event_type_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Resolves a queued human-review task by setting its status (open | in-review | resolved | rejected) and recording the reviewer's chosen resolved_value. resolved_value is optional and defaults to NULL, so a task may be rejected with no payload. Edge cases: status is checked against an explicit whitelist, so a missing OR unrecognised status is a 400; an unknown :task_id returns 404; there is no state-machine guard — re-resolving an already-resolved task is accepted as long as the row still matches, so idempotency must be enforced by the caller.

[
  "POST /api/auth/register",
  "PUT /api/hdk-sync/event-type-policies",
  "POST /api/hdk-sync/conflicts/resolve"
]

{
  "entity": "hdk_sync.human_review_task",
  "field": "status",
  "flow": [
    "open",
    "in-review",
    "resolved",
    "rejected"
  ],
  "transitions": [
    {
      "from": "open",
      "to": "resolved",
      "via": "POST /api/hdk-sync/human-review/:task_id/resolve"
    },
    {
      "from": "open",
      "to": "rejected",
      "via": "POST /api/hdk-sync/human-review/:task_id/resolve"
    },
    {
      "from": "in-review",
      "to": "resolved",
      "via": "POST /api/hdk-sync/human-review/:task_id/resolve"
    }
  ]
}

{
  "task_id": "{{cache:hdk-sync.conflicts-resolve.response.data.human_review_task.task_id}}"
}

{
  "status": "resolved",
  "resolved_value": {
    "decision": "merge"
  }
}

{
  "status": "resolved",
  "resolved_value": {
    "decision": "merge"
  }
}

{
  "success": true,
  "data": {
    "status": "resolved",
    "resolved_value": {
      "decision": "merge"
    },
    "resolve_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Lists the open human-review tasks produced when a conflict's policy is 'human-review'. Optional ?assignee_persona_id= narrows the queue to one reviewer; omitting it returns every open task. Edge cases: an empty queue is 200 with data.tasks = [], never 404; an assignee_persona_id matching nobody also yields an empty list rather than an error; there is no paging or limit parameter, so a large backlog is returned in full.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "open_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Closes a replay batch, stamping it complete with the conflict_count the caller observed. The body is optional — an absent conflict_count defaults to 0. Edge cases: an unknown :batch_id returns 404; a non-UUID :batch_id is not validated by the route, reaches Postgres and surfaces as a 500 rather than a 400; there is no already-completed guard, so behaviour on a double-complete depends on whether the update still matches the row.

[
  "POST /api/auth/register",
  "POST /api/hdk-sync/replay/start"
]

{
  "batch_id": "{{cache:hdk-sync.replay-start.response.data.batch.batch_id}}"
}

{
  "conflict_count": 0
}

{
  "conflict_count": 0
}

{
  "success": true,
  "data": {
    "complete_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conflict_count": 0,
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Opens a replay batch for one device: accepts the offline-queued envelopes a device accumulated and returns the created batch plus the subset that was rejected. Returns 201 even when EVERY envelope is rejected — inspect data.rejected rather than the status code. Edge cases: envelopes must be an array, but an EMPTY array is accepted and creates a zero-item batch; envelopes whose event_type has no registered policy come back in data.rejected instead of failing the request; batch size is not capped by the route, so payload size is bounded only by the gateway body limit; device_uuid and tenant_id come from the body, not the JWT, so tenant scoping is caller-asserted.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant",
  "PUT /api/hdk-sync/event-type-policies"
]

{
  "device_uuid": "test-device-uuid-001",
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}",
  "envelopes": []
}

{
  "device_uuid": "test-device-uuid-001",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "envelopes": []
}

{
  "success": true,
  "data": {
    "start_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "device_uuid": "test-device-uuid-001",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "envelopes": [],
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Returns the hdk-video-editor capability manifest — available tools (trim/merge/caption/mute/speed/overlay), output formats (mp4/hevc/webm), max resolution (4K), and the iOS/Android native module names. The handler is a pure static-metadata read: it takes no body, params or query, touches no database, and always returns HTTP 200 with the same JSON for every caller. QA edge cases: the route is behind requireAuth, so a missing/malformed Authorization header or an expired JWT returns 401 before the handler runs; there is no tenant scoping, so two different tenants receive byte-identical payloads (do not assert per-tenant differences); unknown query params and request bodies are ignored rather than rejected; there is no pagination, no idempotency concern (GET is naturally idempotent), and no 404/409 path because nothing is looked up.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "capability_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Lists every watermark application recorded against one media variant, filtered by the required variant_id query param. QA edge cases: a missing variant_id is a 400, but an unknown variant_id returns 200 with an empty array rather than a 404 — "no such variant" and "variant with no watermarks" are indistinguishable; the listing is unpaginated (no limit/offset), so a variant with many applications returns them all in one response; the query is keyed only by variant_id with no tenant predicate.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant",
  "POST /api/hdk/watermark"
]

{
  "success": true,
  "data": [
    {
      "watermark_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Records a watermark application (visible / invisible / cryptographic) against a media variant, persisting the payload envelope as bytes in hdk_watermark.application and returning 201. payload_envelope is accepted as either base64 or plain utf8 — the service sniffs the string and decodes base64 only when it matches the base64 alphabet AND its length is a multiple of 4, otherwise it stores the raw utf8 bytes. QA edge cases: that sniffing is the subtle one — a short plain-text value that happens to be pure base64 characters with length %4 === 0 will be silently base64-decoded, so byte-length assertions must account for it; an envelope that decodes to zero bytes is rejected as empty even though the field was non-empty; oversized envelopes are rejected above HDK_WATERMARK_MAX_PAYLOAD_BYTES (default 16384 bytes, measured AFTER decoding, not on the string length); every failure — missing field, bad scheme, empty envelope, oversize envelope, insert failure — returns 400, so assert the message; the write is not idempotent (repeat POSTs create additional application rows); tenant_id is optional and defaults to null, so no tenant scoping is enforced on write; the route relies on the gateway default-deny authGate for authentication.

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant"
]

{
  "variant_id": "{{var:variant_id}}",
  "scheme": "visible",
  "payload_envelope": "eyJ3IjoxfQ==",
  "tenant_id": "{{cache:auth.signup-tenant.response.data.tenant_id}}"
}

{
  "variant_id": "{{var:variant_id}}",
  "scheme": "visible",
  "payload_envelope": "eyJ3IjoxfQ==",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "success": true,
  "data": {
    "watermark_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "variant_id": "{{var:variant_id}}",
    "scheme": "visible",
    "payload_envelope": "eyJ3IjoxfQ==",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Fetches a single watermark application from hdk_watermark.application by its application id and returns it as { success: true, data }. QA edge cases: an unknown id returns 404 "not found", and a malformed id returns the same 404, so status alone does not distinguish them; the lookup is not tenant-filtered, so any authenticated caller holding an id can read the record; the response carries the stored payload_envelope bytes, so tests should assert the round-trip of the exact bytes POSTed (remembering the base64-vs-utf8 sniffing performed on write).

[
  "POST /api/auth/register",
  "POST /api/auth/signup-tenant",
  "POST /api/hdk/watermark"
]

{
  "id": "{{cache:watermark.create.response.data.application_id}}"
}

{
  "success": true,
  "data": {
    "watermark_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Standalone pool-federation-runtime chaos-drill endpoint (P7 AC-6) that records a chaos-drill failover_event with measured RPO/RTO, returning 201 with the event. IMPORTANT for QA: this route plugin is also mounted inside the api-gateway with mountHealth:false and NO orchestrator threaded in — because the gateway runs its own orchestrator on /admin/federation/chaos-drill — so against the gateway every authenticated request returns 503 by design, before body validation. Only the standalone binary on :8083 can actually run the drill. Auth differs from the rest of /admin: it is a constant-time compare against the env ADMIN_OPS_TOKEN only, with a length pre-check, so DB-issued admin.ops_token values are NOT accepted here and an unset ADMIN_OPS_TOKEN makes every call 401. Guard order is auth → orchestrator presence → field validation.

{
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2"
}

{
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2"
}

{
  "success": true,
  "data": {
    "chaos_drill_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "federation_id": "{{var:federation_id}}",
    "from_region": "us-east-1",
    "to_region": "us-west-2",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "event_id": "string",
  "federation_id": "string",
  "from_region": "string",
  "to_region": "string",
  "trigger": "string",
  "rpo_observed": "number",
  "rto_observed": "number"
}

Record a failover event (chaos drill, real production failover, or operator-initiated) against federation.failover_event. Body maps 1:1 to recordFailover(); returns the persisted event including server-generated occurred_at.

{
  "event_id": "fov-{{dynamic:slug}}",
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2",
  "trigger": "chaos-drill",
  "rpo_observed": 30,
  "rto_observed": 120
}

{
  "event_id": "fov-{{dynamic:slug}}",
  "federation_id": "{{var:federation_id}}",
  "from_region": "us-east-1",
  "to_region": "us-west-2",
  "trigger": "chaos-drill",
  "rpo_observed": 30,
  "rto_observed": 120
}

{
  "success": true,
  "data": {
    "failover_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "event_id": "fov-{{dynamic:slug}}",
    "federation_id": "{{var:federation_id}}",
    "from_region": "us-east-1",
    "to_region": "us-west-2",
    "trigger": "chaos-drill",
    "rpo_observed": 30,
    "rto_observed": 120,
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "validation failed: a required field is missing or invalid"
}

{
  "trigger": "chaos-drill"
}

Resolves a sanctioned cross-pool federation route: given a federation_id and one of the four sanctioned query classes, returns the federation.route row as {route_id, federation_id, query_class, target_pool_indexes[], execution_plan, created_at, last_used_at}. Reads are cache-first (60s TTL) when a route cache is wired in, falling back to Postgres on miss and writing through; pass ?bypass_cache=true to force the DB read. QA edge cases: query_class is whitelist-validated against exactly ['resolver','dsar','analytics','lineage'] — anything else, including correct-looking values in the wrong case ('Resolver') or a typo, is 400 invalid_query_class, and that check runs BEFORE any lookup. federation_id is not validated at all, so an unknown or malformed federation_id falls through to a 404 route_not_found rather than a 400 — that is the missing-FK signal for this endpoint. bypass_cache is compared strictly to the string 'true', so 'false', '1', 'TRUE' and an omitted param all mean cache-enabled; a stale cache entry can therefore serve a route that was just deleted until the TTL expires, which is why the bypass flag exists. The call is idempotent for the caller but does write asynchronously — it fire-and-forgets an UPDATE of last_used_at, so consecutive reads return a changing last_used_at. Single-row lookup (LIMIT 1), no pagination, no tenant scoping. When mounted standalone on :8083 the route is unauthenticated, but inside the api-gateway /routes/* is not on the authGate.ts public allowlist, so the default-deny gate requires a valid tenant JWT — hence requiresAuth:true. The handler has no try/catch, so a datastore failure surfaces as Fastify's default 500 envelope.

[
  "POST /api/auth/signup-tenant"
]

{
  "federation_id": "{{var:federation_id}}",
  "query_class": "resolver"
}

{
  "success": true,
  "data": {
    "route_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Single dispatch entry point for the registry MCP service: the caller names a tool and passes its arguments, and the service routes to either a read dispatcher or a write dispatcher depending on whether the name is in the write-tool set. Authentication accepts EITHER an Authorization bearer token or an x-projex-api-key header; tenant context is derived from whichever is present, and the resolved tenant is also the rate-limit key. Note that a failing TOOL still returns HTTP 200 — the failure is carried in the body as isError=true with the detail in content[0].text, because the HTTP call itself succeeded. Only transport-level problems (auth, rate limit, malformed request) produce non-2xx. Every invocation is audited with the tool name, duration and error code.

[
  "POST /api/auth/register"
]

{
  "name": "list_sdks",
  "arguments": {}
}

{
  "name": "list_sdks",
  "arguments": {}
}

{
  "success": true,
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "list_sdks",
    "arguments": {},
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

{
  "content": "array",
  "isError": "boolean"
}

Lists agent_definition rows, optionally filtered by tenant_id and tier, with limit/offset paging. Requires a valid tenant JWT (requireAuth). Edge cases: tenant_id is read from the query string, not the JWT, so an absent tenant_id lists across tenants and a foreign tenant_id is NOT rejected - verify tenant scoping deliberately; limit/offset go through parseInt so a non-numeric or empty value yields NaN and surfaces as a 500 "List failed" rather than a 400; an unknown tier value or a tenant with no definitions returns 200 with an empty array, not a 404; a malformed non-UUID tenant_id fails the Postgres uuid cast and becomes a 500.

[
  "POST /api/auth/register"
]

{
  "success": true,
  "data": [
    {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  ],
  "total": 1
}

{
  "success": false,
  "error": "unauthorized: missing or invalid token"
}

Create an agent_definition. Required: name, acting_persona_id, tier, vector_namespace, created_by. Returns the row including server-generated agent_id + timestamps.

[
  "POST /api/auth/register"
]