API docs by Redocly

Axiom Platform API (0.1.32)

Download OpenAPI specification:

Axiom Platform Team: hello@axiom.express License: Proprietary

Axiom is programmable insurance infrastructure: one engine for every line of insurance, where the rules are data and every decision can be explained to the person it affects.

Overview

Axiom provides a complete REST API across the five universal insurance primitives — parties/roles, products/covers, policies/versions, premiums/payments, and events/assertions (under the governed contract). Every feature is designed API-first under the governed contract.

Authentication

All API requests (except health checks) require:

  • Bearer token via Authorization header (JWT from auth service)
  • Tenant context via X-Tenant-Context header (server-minted token, required on tenant-scoped endpoints)

Response Format

Most endpoints currently return a legacy envelope format:

{
  "data": { ... },
  "status": "success",
  "message": "optional description"
}

Error responses:

{
  "error": "Human-readable error message",
  "status": "error"
}

Newer endpoints (inbox, ingress, webhooks, vendors) use the JSON:API format under the governed contract. Migration of legacy endpoints to JSON:API is planned.

Pagination

List endpoints declare their pagination profile per operation. Newer converged list endpoints use cursor-based pagination:

  • page[size] — maximum items per page
  • page[after] — opaque cursor from the previous page

Legacy alpha list endpoints may still use offset-based pagination until they are migrated:

  • limit — maximum items per page
  • offset — number of items to skip

Cursor response metadata includes has_more and may include next_cursor. Offset response metadata includes total, limit, and offset.

Example offset metadata:

{
  "data": [...],
  "meta": { "total": 150, "limit": 20, "offset": 0 },
  "status": "success"
}

Correlation Tracing

Include X-Correlation-ID header for end-to-end request tracing. If omitted, the server generates one. The response always includes X-Correlation-ID for support reference.

Versioning

API families are in the URL path (/v1/...). The published contract version is SemVer and is emitted in info.version, X-API-Version, and response telemetry under the governed contract.

Rate Limiting

When a tenant-scoped route has an active runtime rate-limit policy, responses include budget headers:

  • X-RateLimit-Limit — active tenant policy limit for the route
  • X-RateLimit-Remaining — remaining requests in the current window
  • X-RateLimit-Reset — window reset time (Unix timestamp)

Rejected calls return 429 with Retry-After.

Analytics

Dashboard metrics, claims analysis, revenue trends, and product performance.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Get dashboard metrics

Published for route accountability in API 0.1.0. The runtime currently returns 501 until tenant-owned analytics projections are implemented.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Get claims breakdown by status

Published for route accountability in API 0.1.0. The runtime currently returns 501 until tenant-owned analytics projections are implemented.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Get monthly revenue trend

Published for route accountability in API 0.1.0. The runtime currently returns 501 until tenant-owned analytics projections are implemented.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Get top products by premium volume

Published for route accountability in API 0.1.0. The runtime currently returns 501 until tenant-owned analytics projections are implemented.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Assertion

Assertions — the per-event contract-response record (the canonical events/assertions paired primitive, governed contract). Read-only surface (GET + LIST). Lifecycle: pending → settled → reopened → adjusted → finalised.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List assertions

Retrieve a cursor-paginated list of assertions for the operating tenant (tenant-isolated). Results are sorted by recorded_at descending (newest physical write first), tie-broken by id for stable pagination.

Filter by event_id, cover_id, rule_version_id, and/or status (query params). A bogus status value returns 400 with the accepted set in the error meta. Legacy limit/offset pagination is rejected; clients must use page[size] and page[after].

Response uses the canonical success envelope format with cursor metadata.

Authorizations:
BearerAuth
query Parameters
event_id
string

Filter to assertions responding to this event

cover_id
string

Filter to assertions determined under this cover

rule_version_id
string

Filter to assertions produced by this rule version

status
string
Enum: "pending" "settled" "reopened" "adjusted" "finalised"

Filter to assertions in this lifecycle status

page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of assertions to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Get an assertion by ID

Retrieve a single assertion by its physical row UUID, scoped to the operating tenant (tenant-isolated). A cross-tenant id returns 404.

Response uses the canonical success envelope format.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique assertion identifier (physical row UUID)

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Audit

Audit trail — recent audit entries for compliance and debugging.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Get recent audit entries

Returns recent audit log entries for the tenant, ordered by timestamp descending (newest first).

Audit entries record all significant actions: resource creation, updates, deletions, state transitions, authentication events, and compliance checks.

Supports filtering by subject type and cursor-based pagination. Legacy limit/offset pagination is rejected; clients must use page[size] and page[after].

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 50 ]
Default: 10

Maximum number of audit entries to return in this cursor page (default 10, max 50)

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

subject_type
string
Example: subject_type=policy

Filter by subject type (e.g. policy, claim, party, vendor, product). When omitted, returns entries for all subject types.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "meta": {
    }
}

Benefit

Benefit balance computation (governed contract). Parameterised queries for benefit utilisation, available balance, and usage decomposition.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Apply Proration Adjustment

Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

Optional premium identity in wire form when the decision affects a known premium.

product_id
required
string

Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "premium_id": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "product_id": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "proration_intent": "mid_year_join",
  • "reason": "string",
  • "correction_of_decision_id": "e12d0bbe-ce81-4547-b5ce-7b1ddd242520",
  • "affected": {
    },
  • "effective_times": {
    },
  • "inputs": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get benefit balance

Returns the current balance for a specific benefit type on a policy, showing how much of the benefit limit has been consumed.

Supports point-in-time queries via as_of and period-scoped queries via period_start/period_end for benefits with annual or periodic limits (e.g. annual dental limit, per-incident excess cap).

under the governed contract, benefit balances are computed from the ledger and are always consistent with claim payouts and adjustments.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string <uuid>
Example: policy_id=cc347178-b31f-571d-8ed1-b2513427d36f

Policy UUID to query benefits for

benefit_type
required
string
Example: benefit_type=hospitalisation

Benefit type identifier (e.g. hospitalisation, dental, optical, roadside_assistance, personal_accident).

period_start
string <date>
Example: period_start=2026-01-01

Start of the benefit period (ISO 8601 date)

period_end
string <date>
Example: period_end=2026-12-31

End of the benefit period (ISO 8601 date)

as_of
string <date-time>
Example: as_of=2026-03-12T00:00:00Z

Point-in-time query. Returns the benefit balance as it was at this timestamp. Defaults to current time if omitted.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Get available benefit amount

Returns the currently available (claimable) amount for a benefit type on a policy, accounting for in-flight claims that have been filed but not yet settled.

This differs from /balance in that it includes pending claims as reserved amounts, giving a more conservative view of availability suitable for claim intake decisions.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string <uuid>
Example: policy_id=cc347178-b31f-571d-8ed1-b2513427d36f

Policy UUID to query benefit availability for

benefit_type
required
string
Example: benefit_type=dental

Benefit type identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Get Proration Balance

Read a tenant-owned policy-scoped balance derived from accepted proration decision components for implemented governed contract proration consumers. Slice 1 supports fund and earning balances; treaty-scoped reinsurance balances fail closed until governed treaty authority exists.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

consumer
required
string
Enum: "fund_balance" "earning_balance" "reinsurance_balance"

Implemented proration balance consumer. reinsurance_balance is an accepted fail-closed value until governed treaty authority exists.

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

Fund account code, required for fund_balance unless account_code is supplied.

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

Earning period key, required for earning_balance unless account_code is supplied.

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Catalogue

Catalogue parent lifecycle, bi-temporal entries, temporal values, relationships, labels, descriptor, source provenance, and bulk-write operations. Governed by governed contract.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List catalogues

Returns catalogue parents visible to the caller's tenant. Tenant-scoped catalogues from other tenants are filtered out (not 404'd individually). Tenant isolation is enforced at the persistence layer by tenant-isolated.

Optional slug filter for exact slug match; include_discarded exposes soft-discarded parents for audit / recovery purposes (defaults false).

Authorizations:
BearerAuth
query Parameters
slug
string

Exact catalogue slug filter (e.g. icd-10-za).

include_discarded
boolean

When true, includes soft-discarded catalogue parents in the result.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get catalogue

Fetch a single catalogue parent by its slug identifier. Returns discarded parents too (audit / as-was reconstruction); the discarded_at, discarded_by, and discard_reason fields are populated when set.

Tenant isolation enforced at persistence layer by tenant-isolated. Cross-tenant slugs yield 404, not 403.

Authorizations:
BearerAuth
path Parameters
catalogue-ref
required
string

Logical catalogue identifier (slug, e.g. icd-10-za).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List bi-temporal entries

Returns bi-temporal catalogue entries for the given catalogue parent, filtered by the two-axis as-was window (as_of / recorded_at). Tenant isolation enforced at the persistence layer by tenant-isolated.

Optional filters:

  • logical_entry_id — return all versions of a single logical entry UUID.
  • code — exact code match.
  • q — keyword search on description.
  • order_by=attr.<field> — sort by a descriptor-declared attribute field (contract rule; fails 400 DESCRIPTOR_FIELD_NOT_SORTABLE when the field is not declared in the catalogue descriptor's roles.sort.fields).
  • dir=asc|desc — sort direction (default asc).
  • attr.<key>=<value> — JSONB-containment filter on any attribute field (contract rule; when the catalogue descriptor declares roles.search.fields, only declared fields are accepted; undeclared → 400 DESCRIPTOR_FIELD_NOT_SEARCHABLE).
Authorizations:
BearerAuth
path Parameters
catalogue-ref
required
string

Logical catalogue identifier (slug, e.g. icd-10-za).

query Parameters
as_of
string <date-time>

Real-world validity axis instant (RFC 3339). When provided, only entries whose valid_from <= as_of < valid_to (or valid_to IS NULL) are returned.

recorded_at
string <date-time>

Physical-anchor axis instant (RFC 3339). When provided, only entries whose recorded_from <= recorded_at are returned, enabling as-was reconstruction at a prior recording moment.

logical_entry_id
string <uuid>

UUID of the logical entry; returns all bi-temporal versions for that entry.

code
string

Exact code match filter.

q
string

Keyword search on the entry description field.

order_by
string

Attribute sort field in the form attr.<field>. Only fields declared in the catalogue descriptor roles.sort.fields are accepted (contract rule allow-list).

dir
string
Enum: "asc" "desc"

Sort direction. One of asc or desc. Defaults to asc.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "count": 1
}

Atomically create N relationships in one transaction

Atomic batch create under the governed contract. Either every row in the relationships array is persisted, or none are. The path :catalogue-ref scopes the batch — every row's source_catalogue MUST equal the path. Unlike the single-create endpoint, source fields are NOT defaulted from the path; each row must specify them explicitly. Maximum batch size is 10000 (BATCH_SIZE_EXCEEDED 400 above that).

Authorizations:
BearerAuth
path Parameters
catalogue-ref
required
string

Logical catalogue identifier (e.g. icd-10-za).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
required
Array of objects (CatalogueRelationshipBody) [ 1 .. 10000 ] items

Responses

Request samples

Content type
application/json
{
  • "relationships": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Claim

Claims processing — submission, assessment, payment, and closure. Status: submitted → assessing → assessed → approved → paying → paid → closed. Also: submitted → rejected → closed. Deprecated (RFC-8594; Sunset 2026-08-31) in favour of Assertion.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Submit a new claim

Submit an insurance claim against a policy. The claim is created in "submitted" status and enters the claims workflow for assessment.

The referenced policy must be active (or within its coverage period for the event date). The event must fall within the policy's effective period.

The system validates coverage eligibility, checks for duplicate claims, and triggers any configured automated rules (e.g. fraud scoring).

Side effects: persists the claim in submitted status; initiates the claims workflow (automated triage and assessment assignment); emits an audit entry recording the submission.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema:
required
event_id
required
string <uuid>

Reference to the insured event

policy_id
required
string <uuid>

Reference to the policy under which the claim is submitted

primary_party_id
required
string <typed-prefix-id>

Reference to the primary claimant party

description
required
string

Description of the claim circumstances

required
object

Total amount being claimed (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty.

event_date
required
string <date>

Date when the insured event occurred (ISO 8601 date)

priority
string (ClaimPriority)
Enum: "low" "medium" "high" "urgent"

Claim priority level:

  • low — Routine claim, standard handling priority (e.g. minor property damage)
  • medium — Standard claim requiring timely processing (e.g. motor accident)
  • high — Significant claim requiring expedited handling (e.g. business interruption)
  • urgent — Critical claim requiring immediate attention (e.g. hospitalisation, total loss)
object or null

Extensible attributes for tenant-specific claim data

object or null

Operational metadata (integration references, source system info)

Responses

Request samples

Content type
Example
{
  • "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c",
  • "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd",
  • "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420",
  • "description": "Rear-end collision at intersection of 5th Avenue and 42nd Street, New York. Third-party vehicle damage and whiplash injury to driver.",
  • "claimed_amount": {
    },
  • "event_date": "2026-03-01",
  • "priority": "medium",
  • "attributes": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Claim submitted successfully",
  • "telemetry": {
    }
}

List claims

Retrieve a cursor-paginated list of claims for the tenant. Results are sorted by created_at descending with id as a stable tie-breaker. Sort order is not configurable.

Returns claims across all statuses (submitted, under_review, assessed, partial_approval, denied, paid, closed).

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of claims to return in this page

page[after]
string

Opaque cursor returned as meta.next_cursor from the previous page. Do not construct or modify this value.

policy_id
string

Optional filter — return only claims against this policy. Accepts the canonical typed-prefix policy id (pol_…, governed contract). A malformed value returns 400. Absent = all claims for the tenant (current behaviour). Composes with the existing operating-tenant tenant-isolated scope; never widens it.

party_id
string

Optional filter — return only claims whose primary party is this party (primary_party_id). Accepts the canonical typed-prefix party id (pty_…, governed contract). A malformed value returns 400. Absent = all claims for the tenant (current behaviour). Composes with the existing operating-tenant tenant-isolated scope; never widens it.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success",
  • "telemetry": {
    }
}

Get a claim by ID

Retrieve a single claim with its full details including claim items, assessments, payments, and current workflow state.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "telemetry": {
    }
}

Assess a claim

Submit an assessment for a claim. Assessments record the outcome of investigation and evaluation, including approved amounts and per-item assessments.

The claim must be in "under_review" status. After assessment, the claim transitions to "assessed" (full approval), "partial_approval", or "denied".

Automated rule evaluation results (e.g. fraud scoring) are included in the assessment record for audit and explainability.

Side effects: returns the assessment result with the claim status transitioned (under_review to assessed, partial_approval, or denied) without persisting the changes. Emits an audit entry when audit is configured.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
assessed_by
required
string

Identifier of the assessor performing the assessment

assessment_notes
required
string

Detailed notes from the assessment

object or null

Approved claim amount. Null if recommending denial.

Array of objects or null (ItemAssessment)

Per-item assessment details

object or null

Operational metadata for the assessment

Responses

Request samples

Content type
application/json
Example
{
  • "assessed_by": "assessor-jvd-001",
  • "assessment_notes": "Site inspection completed. Damage verified against police report and repair quotations from two panel beaters. Approved less R5,000 policy excess.",
  • "approved_amount": {
    },
  • "item_assessments": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "assessment": [
    ],
  • "status": "success",
  • "message": "Claim assessed successfully using tenant-specific adjudication rules",
  • "telemetry": {
    }
}

Record a claim authorisation

Record an governed contract authorisation sub-event against a claim. The row is append-only and carries the authorising actor, authorised scope, budget, governing-version binding, optional compliance state, decision date, and explanation-node reference.

Claim payments may cite the returned authorisation id. When they do, the payment path runs the authorisation compliance gate before disbursement.

Side effects: persists an authorisation_transitions row under the tenant context and returns the recorded authorisation.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
logical_authorisation_id
string or null <uuid>

Logical thread id for grant/amend/revoke chains. Generated when omitted.

transition_kind
required
string

Sector-neutral transition verb.

authorisation_kind
required
string

Tenant-keyed authorisation kind.

authorising_actor
required
string <uuid>

Party-in-role actor that granted the authorisation.

object

Typed grant envelope such as procedures, codes, or engagement scope.

budget_minor
integer or null <int64>

Exact integer minor units for the authorised budget ceiling.

budget_currency_code
string or null^[a-z]{3}$

Lowercase ISO-4217 currency code. Present iff budget_minor is present.

governing_version_kind
string or null

Governing-version discriminator such as catalogue, rule, cover, or engagement-terms.

governing_version_row_id
string or null <uuid>

Immutable row-id revision of the governing version current at the decision date.

compliance_kind
string or null

Tenant-keyed compliance kind such as accreditation or sanctions-screening.

compliance_outcome
string or null
Enum: "clear" "hit" "pending" "unset" "override"

Compliance outcome consulted by the payment gate when payment cites this authorisation.

compliance_list_version
string or null

Tenant-supplied as-was list or standard version.

compliance_list_authority
string or null

Tenant-keyed list authority such as cms, ofac, ofsi, or eu.

decision_date
required
string <date-time>

Moment the authorisation decision was made.

explanation_node_id
required
string <uuid>

Explanation-node reference for the authorisation decision.

finding_reference
string or null <uuid>

Required by the persistence rule on revoke or withdrawal transitions.

Responses

Request samples

Content type
application/json
{
  • "transition_kind": "authorisation-granted",
  • "authorisation_kind": "pre-auth",
  • "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea",
  • "authorised_scope": {
    },
  • "budget_minor": 250000,
  • "budget_currency_code": "zar",
  • "governing_version_kind": "catalogue",
  • "governing_version_row_id": "b1468ab8-97c1-5aa6-aca6-9430e182a5bd",
  • "decision_date": "2026-07-06T10:00:00Z",
  • "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Claim authorisation recorded successfully"
}

Process a claim payment

Initiate payment for an assessed claim. The claim must be in "assessed" or "partial_approval" status before payment can be processed.

Payment is recorded against the claim and linked to the billing/payments subsystem. The claim transitions to "paid" once the payment is confirmed.

Invalid transitions return HTTP 422 with error code INVALID_STATE_TRANSITION.

Side effects: returns the constructed payment record and ledger entries with the claim status transitioned to paid, without persisting the changes. Emits an audit entry when audit is configured.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
required
object

Amount to disburse (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty.

payment_method
required
string

Payment disbursement method

payment_notes
string or null

Notes accompanying the payment

processed_by
required
string

Identifier of the user or system processing the payment

authorisation_id
string or null <uuid>

governed contract authorisation row to cite and gate before payment.

object or null

Operational metadata for the payment

Responses

Request samples

Content type
application/json
Example
{
  • "paid_amount": {
    },
  • "payment_method": "bank_transfer",
  • "payment_notes": "Final settlement — approved amount less policy excess",
  • "processed_by": "payments-officer-mk-003",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "ledger_entries": [
    ],
  • "status": "success",
  • "message": "Claim payment processed successfully",
  • "telemetry": {
    }
}

Close a claim

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the claim close workflow, terminal-state authority, and irreversible closure audit semantics are implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
closure_reason
string

Reason for closing the claim

closed_by
string

Identifier of the user or system closing the claim

Responses

Request samples

Content type
application/json
Example
{
  • "closure_reason": "Final settlement disbursed and accepted by claimant",
  • "closed_by": "claims-manager-001"
}

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Generate a claim PDF report

Generate a PDF document summarising the claim, including the event details, assessment results, payment information, and workflow history.

The PDF is generated on demand and returned as a binary response. For large claims with extensive documentation, generation may take several seconds.

The generated PDF includes:

  • Claim header (claim number, policy number, status)
  • Event details and description
  • Claim items with amounts
  • Assessment summary and notes
  • Payment details (if applicable)
  • Workflow timeline

This endpoint returns binary PDF data (application/pdf), not a JSON envelope.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Create a claim reserve

Create a new active reserve for a claim. The amount must be a positive integer in cents. On success the reserve is created with state "active", current_amount == initial_amount, and released_amount == 0.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
reserve_type
required
string
amount
required
integer <int64>
reason
string

Responses

Request samples

Content type
application/json
{
  • "reserve_type": "case_estimate",
  • "amount": 500000,
  • "reason": "initial case estimate"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List reserves for a claim

Retrieve all reserves for a claim, ordered by established_at descending. Returns explanation-ready reserve facts.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get a single reserve

Retrieve a single reserve by ID with explanation-ready facts.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

reserveId
required
string

Unique reserve identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update an active reserve

Only reserves in "active" state can be updated.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

reserveId
required
string

Unique reserve identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
amount
required
integer <int64>
reason
string

Responses

Request samples

Content type
application/json
{
  • "amount": 600000,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Release reserve amount

Partial release yields "partially_released"; full release yields "fully_released". Over-release returns HTTP 422.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

reserveId
required
string

Unique reserve identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
amount
required
integer <int64>
reason
string

Responses

Request samples

Content type
application/json
{
  • "amount": 300000,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Cancel an active reserve

Only reserves in "active" state can be cancelled. Returns inactive reserve with zero remaining exposure.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

reserveId
required
string

Unique reserve identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Re-establish a terminal reserve

Create a new active reserve linked to a terminal predecessor. Re-establishment from "active" or "partially_released" is rejected.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

reserveId
required
string

Unique reserve identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
amount
required
integer <int64>
reason
string

Responses

Request samples

Content type
application/json
{
  • "amount": 750000,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List reserves by policy

policy_id query parameter is required.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string <uuid>
active_only
boolean
Default: false
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Create or advance an SIU investigation

Create a new SIU investigation on a claim, or advance an existing open investigation by exactly one state. The endpoint uses create-or-advance semantics: the first POST with target_state=assigned creates the investigation (HTTP 201); subsequent POSTs advance the open investigation (HTTP 200).

State machine: assigned → investigating → findings_submitted → closed. Disposition (substantiated|unsubstantiated|settled) is required only when target_state=closed.

settled closes the SIU investigation only — it does not change claim status, create recovery, or affect normal adjudication.

Every transition persists immutable evidence and an explanation tree in the same transaction (governed contract). Actor provenance is sourced from the authenticated request context (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
target_state
required
string
Enum: "assigned" "investigating" "findings_submitted" "closed"

The target workflow state for this transition.

trigger_source
string
Enum: "rule_threshold" "human_referral"

Required on creation; immutable on subsequent advances.

assigned_party_id
string

Required on creation; immutable on subsequent advances.

assigned_role_type
string

Required on creation; immutable on subsequent advances.

reason
string

Required on creation.

evidence_refs
Array of strings

Required and non-empty on creation.

fraud_rule_refs
Array of strings

Required and non-empty when trigger_source=rule_threshold.

disposition
string
Enum: "substantiated" "unsubstantiated" "settled"

Required when target_state=closed; forbidden otherwise.

Responses

Request samples

Content type
application/json
Example
{
  • "target_state": "assigned",
  • "trigger_source": "rule_threshold",
  • "assigned_party_id": "party-siu-001",
  • "assigned_role_type": "siu_investigator",
  • "reason": "Fraud score 0.87 exceeded investigation threshold",
  • "evidence_refs": [
    ],
  • "fraud_rule_refs": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Investigation advanced",
  • "telemetry": {
    }
}

Record a recovery event for a claim

Records a subrogation or salvage recovery event with balanced ledger posting, explanation tree, and evidence — all atomically in a single transaction. Requires X-Tenant-Context and Idempotency-Key headers.

Authorizations:
BearerAuth
path Parameters
claimId
required
string
header Parameters
X-Tenant-Context
required
string
Idempotency-Key
required
string
Request Body schema: application/json
required
recovery_type
required
string
Enum: "subrogation" "salvage"

Type of recovery. Closed enum. subrogation: claim-level recovery against a liable third party. salvage: item-level recovery from damaged goods.

claim_item_id
string <typed-prefix-id>

Required for salvage, forbidden for subrogation. References the specific claim item being salvaged.

third_party_party_id
string <typed-prefix-id>

Required for subrogation, optional for salvage. References the liable third-party via party ID.

amount
required
string^[1-9]\d*$

Recovery amount as string-encoded exact decimal in the smallest currency unit (e.g. cents). String encoding under the contract contract; no float on financial paths (governed contract).

currency
required
string

ISO 4217 currency code

received_at
required
string <date-time>

When the recovery was received (RFC 3339)

reason
required
string

Reason for the recovery

evidence_refs
required
Array of strings non-empty

Non-empty array of evidence references supporting this recovery

Responses

Request samples

Content type
application/json
{
  • "recovery_type": "subrogation",
  • "claim_item_id": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5",
  • "third_party_party_id": "pty_01j9zxkp8wqrm2n4v6t5s3d7f9",
  • "amount": "5000000",
  • "currency": "USD",
  • "received_at": "2026-03-15T10:30:00Z",
  • "reason": "Third party liability established via settlement agreement",
  • "evidence_refs": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Record a correction for a recovery event

Creates a correction (full reversal, partial reversal, or write-off) for an existing recovery using compensating ledger entries. Never deletes or updates original entries (governed contract). Requires X-Tenant-Context and Idempotency-Key headers.

Authorizations:
BearerAuth
path Parameters
claimId
required
string
recoveryId
required
string
header Parameters
X-Tenant-Context
required
string
Idempotency-Key
required
string
Request Body schema: application/json
required
correction_type
required
string
Enum: "full_reversal" "partial_reversal" "write_off"

Type of correction. Closed enum. full_reversal: reverses the full original amount. partial_reversal: reverses a specified portion. write_off: writes off a specified or full amount.

amount
string or null^[1-9]\d*$

Required for partial_reversal, forbidden for full_reversal, optional for write_off. String-encoded exact decimal in smallest currency unit (e.g. cents). No float (governed contract).

reason
required
string

Reason for the correction

evidence_refs
required
Array of strings non-empty

Non-empty array of evidence references supporting this correction

effective_at
required
string <date-time>

When the correction is effective (RFC 3339)

Responses

Request samples

Content type
application/json
{
  • "correction_type": "full_reversal",
  • "amount": "2500000",
  • "reason": "Recovery recorded in error — settlement rescinded",
  • "evidence_refs": [
    ],
  • "effective_at": "2026-03-18T14:00:00Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Compliance

Compliance evaluation engine (governed contract). Evaluates subjects against regulatory requirements and produces compliance reports.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Get a compliance evaluation report

Returns a compliance report for a completed evaluation, including per-jurisdiction findings, pack metadata, and explanation tree reference.

under the governed contract: compliance_assertion is always false — reports are evidence-enabling, not compliance-asserting.

Authorizations:
BearerAuth
path Parameters
evaluation_id
required
string <uuid>
Example: 6b6487c1-bf44-5a61-ad58-caf256e207b6

Compliance evaluation UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Contract

Generated OpenAPI contract served by the deployed API binary.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Get the deployed OpenAPI contract

Returns the generated OpenAPI 3 contract embedded in the running API binary. The SHA-256 digest of this exact document is exposed on /v1/health under contract.sha256 for deployed-contract verification.

Responses

Response samples

Content type
application/json
{
  • "openapi": "3.0.3",
  • "info": { },
  • "paths": { }
}

Get the deployed OpenAPI contract

Versioned alias for /openapi. Returns the generated OpenAPI 3 contract embedded in the running API binary.

Responses

Response samples

Content type
application/json
{
  • "openapi": "3.0.3",
  • "info": { },
  • "paths": { }
}

Get async job status

Returns the current state of an async job. Terminal states (succeeded, failed, dead_letter) are cacheable; non-terminal states (queued, running) are returned with no-store.

The response is a bare {data: ...} envelope (no status field).

Authorizations:
BearerAuth
path Parameters
job_id
required
string <uuid>
Example: 310cf32d-9203-5f14-9574-38c755ef42fa

UUID of the async job to poll.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Event

Event and assertion workflows exposed in the developer-preview API.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List events

Retrieve a cursor-paginated list of events (real-world incidents) for the operating tenant (tenant-isolated). Sorted by occurred_at descending (most recent incident first), tie-broken by id for stable pagination. Filter by event_type, status, and/or policy_id (query params); event_type and status are free-form domain strings, so a non-matching value simply matches nothing.

Legacy limit/offset pagination is rejected; clients must use page[size] and page[after].

Authorizations:
BearerAuth
query Parameters
event_type
string

Filter to events of this type

status
string

Filter to events in this lifecycle status

policy_id
string

Filter to events reported against this policy

page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of events to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Get an event by ID

Retrieve a single event by its id, scoped to the operating tenant (tenant-isolated). A cross-tenant id returns 404.

Authorizations:
BearerAuth
path Parameters
id
required
string

Event id (wire form)

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Upload documents to an event

Multipart upload of one or more files attached to an existing event. Every file part in the form is ingested into the archive and linked to the event.

Authorizations:
BearerAuth
path Parameters
event_id
required
string

Event id (typed-prefix wire form).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: multipart/form-data
required
property name*
additional property
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Report Event

Record a tenant-reported event with supporting documents. An event is the Axiom assertion primitive — it captures what happened, who reported it, and what documentary evidence supports it. The operation is idempotency-optional; events are append-only and duplicate-safe through the assertion model. Ledger effects, if any, are produced by downstream rules evaluation against the stored assertion.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: multipart/form-data
required
event_data
required
string

JSON object (as a string) describing the event. Supported fields mirror the Event projection's tenant-reportable fields: event_id, event_type, event_subtype, occurred_at, reported_at, policy_id, policy_object_id, primary_party_id, event_details, metadata, description, and the other optional event facts exposed on the Event schema.

property name*
additional property
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Apply Proration Adjustment

Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

Optional premium identity in wire form when the decision affects a known premium.

product_id
required
string

Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "premium_id": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "product_id": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "proration_intent": "mid_year_join",
  • "reason": "string",
  • "correction_of_decision_id": "e12d0bbe-ce81-4547-b5ce-7b1ddd242520",
  • "affected": {
    },
  • "effective_times": {
    },
  • "inputs": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Evidence

Evidence records and packs for audit and compliance (governed contract). Tamper-evident records with content hashing and integrity verification.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Initiate a presigned object upload

Returns a short-lived presigned PUT URL the caller uses to upload a binary payload directly to object storage (S3-compatible), bypassing the API for the bytes themselves. The returned upload_id is then referenced in a downstream ingest call (e.g. POST /v1/catalogues/{catalogue-ref}/bulk-write).

The response is a bare {data: ...} envelope (no status field).

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{}

Upload an object to the archive

Multipart upload of a single binary payload into the Axiom archive. The file part is required; original_filename, mime_type, and source are optional. When omitted, the API derives them from the file header, Content-Type, and literal source "api".

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: multipart/form-data
required
file
required
string <binary>

The binary payload to archive.

original_filename
string

Original filename; falls back to the upload part's filename.

mime_type
string

MIME type; falls back to the part Content-Type or application/octet-stream.

source
string

Provenance tag (default "api").

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Report Event

Record a tenant-reported event with supporting documents. An event is the Axiom assertion primitive — it captures what happened, who reported it, and what documentary evidence supports it. The operation is idempotency-optional; events are append-only and duplicate-safe through the assertion model. Ledger effects, if any, are produced by downstream rules evaluation against the stored assertion.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: multipart/form-data
required
event_data
required
string

JSON object (as a string) describing the event. Supported fields mirror the Event projection's tenant-reportable fields: event_id, event_type, event_subtype, occurred_at, reported_at, policy_id, policy_object_id, primary_party_id, event_details, metadata, description, and the other optional event facts exposed on the Event schema.

property name*
additional property
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Create an evidence record

Creates a new evidence record capturing a decision, evaluation, or state transition for audit and compliance purposes.

Evidence records are immutable once created. The content_hash (SHA-256) is computed server-side and enables tamper detection.

Supports platform principle (Explainability) — every material decision emits a durable explanation tree stored as evidence.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
record_type
required
string

Classification of the evidence record

subject_type
required
string

Type of the entity this evidence pertains to

subject_id
required
string

Identifier of the subject entity

required
object

Structured evidence payload

created_by
string

Identifier of the creating user or service

Responses

Request samples

Content type
application/json
{
  • "record_type": "rule_evaluation",
  • "subject_type": "policy",
  • "subject_id": "e316666f-e293-5ccc-81a8-8a12fe4094c5",
  • "content": {
    },
  • "created_by": "pricing-engine"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get an evidence record by ID

Returns a single evidence record including its full content payload and integrity hash.

Authorizations:
BearerAuth
path Parameters
evidence_id
required
string <uuid>
Example: c0e531a6-9deb-53a8-873b-9736a707f52b

Evidence record UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Query evidence records

Searches evidence records using structured filters. Supports filtering by subject, record type, date range, and content attributes.

POST is used instead of GET to support complex query payloads that exceed URL length limits.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
subject_type
string

Filter by subject type

subject_id
string

Filter by subject identifier

record_type
string

Filter by evidence record type

from_date
string <date-time>

Filter records created on or after this timestamp

to_date
string <date-time>

Filter records created before this timestamp

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of records to return

offset
integer >= 0
Default: 0

Number of records to skip

Responses

Request samples

Content type
application/json
{
  • "subject_type": "claim",
  • "subject_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237",
  • "record_type": "decision_trace",
  • "from_date": "2026-03-01T00:00:00Z",
  • "limit": 50
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Verify integrity of a single evidence record

Recomputes the content hash for the specified evidence record and compares it against the stored hash. Returns a verification result indicating whether the record has been tampered with.

Authorizations:
BearerAuth
path Parameters
evidence_id
required
string <uuid>
Example: c0e531a6-9deb-53a8-873b-9736a707f52b

Evidence record UUID to verify

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Batch-verify evidence record integrity

Verifies the integrity of multiple evidence records in a single request. Useful for periodic compliance audits or spot checks.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
evidence_ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

List of evidence record IDs to verify

Responses

Request samples

Content type
application/json
{
  • "evidence_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Assemble an evidence pack

Assembles a collection of evidence records into a named pack. Evidence packs provide a complete audit trail for a decision or event, bundling all related records for compliance reporting and review.

under the governed contract, packs are assembled on demand from existing records and are themselves immutable once created.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
name
required
string

Descriptive name for the evidence pack

record_ids
required
Array of strings <uuid> [ items <uuid > ]

List of evidence record IDs to include in the pack

assembled_by
string

Identifier of the user or service assembling the pack

Responses

Request samples

Content type
application/json
{
  • "name": "Claim CLM-2026-00142 — Marine Cargo Adjudication Evidence Pack",
  • "record_ids": [
    ],
  • "assembled_by": "compliance-reporting-service"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get an evidence pack by ID

Returns an evidence pack including all constituent evidence records.

Authorizations:
BearerAuth
path Parameters
pack_id
required
string <uuid>
Example: 00548ee3-5ea2-5e09-8975-93b2e0fe033e

Evidence pack UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Health

Service health and readiness checks. No authentication required.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Check API health

Returns the current developer-facing API health status. Use this endpoint for connectivity checks and include X-Correlation-ID when escalating an unexpected result.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "timestamp": "2026-08-09T00:00:00Z",
  • "version": "0.1.32"
}

Identity

Authenticated actor, admitted tenant discovery, and tenant-context bootstrap.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List admitted tenants

Returns the tenants admitted for the authenticated actor. Use the returned tenant selection data to request a server-minted tenant context.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Mint tenant context

Mints a server-authoritative tenant-context token for one admitted tenant. Use that token as the X-Tenant-Context header on tenant-scoped API calls.

Authorizations:
BearerAuth
Request Body schema: application/json
required
tenant_id
required
string <typed-prefix-id> ^tnt_[0-9A-HJKMNP-TV-Z]{26}$

Tenant identifier selected from GET /v1/me/tenants.

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "tnt_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Inbox

Inbound message ingestion (governed contract). Durable, idempotent message intake with deduplication. Uses JSON:API response format.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Receive an inbound message

Accepts an inbound message into the Axiom inbox for processing.

The inbox is the single entry point for external messages (emails, notifications, partner communications) entering the platform. Messages are deduplicated using the deduplication_key and routed to the appropriate processing workflow.

Response format: canonical success envelope.

Idempotency: Sending the same deduplication_key twice returns the same inbox_message_id without creating a duplicate.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
source
required
string

Identifier of the message source system or channel (e.g. email gateway, partner API, broker portal).

message_type
required
string

Type classification for routing (e.g. claim_notification, payment_confirmation, policy_amendment_request, document_upload).

deduplication_key
required
string

Client-provided idempotency key. Messages with the same key are deduplicated — only the first is processed.

required
object

Message payload. Structure varies by message_type.

object

Optional metadata (timestamps, routing hints, source headers)

Responses

Request samples

Content type
application/json
Example
{
  • "source": "partner-api-stripepay",
  • "message_type": "payment_confirmation",
  • "deduplication_key": "stripepay-txn-2026-03-12-00142",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

Ingress

Async event ingestion (governed contract). Conditionally available event intake with transformation pipeline support. Uses JSON:API response format.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Ingest an event

Accepts an event into the Axiom ingress pipeline for processing.

This is an admitted alpha transport surface for asynchronous external inputs. It persists a durable inbox record and returns 202 Accepted before downstream processing. It is not a public self-service event catalogue, and event-type schemas are not yet published as a generated contract fragment. Event types, payload schemas, and promotion rules are tenant-owned configuration when promoted; they are not Axiom-owned public domain content.

Conditional availability: This endpoint may return 404 if async ingress is not enabled in the environment.

Response format: JSON:API style — not the legacy wrapper.

Idempotency: Events are deduplicated using X-Webhook-Delivery-ID when supplied. If the header is absent, the runtime derives a stable key from the source and request body bytes. Resubmitting the same key returns the original ingress_id.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
event_type
required
string

Tenant-owned external event type identifier. The public developer-preview contract does not publish a stable event type catalogue; use only values supplied in an issued tenant integration runbook.

source
string

Optional source hint. The runtime may derive source from the authenticated context or X-Source header.

occurred_at
string <date-time>

When the event actually occurred (as opposed to when it was received). If omitted, the server uses the receipt timestamp.

required
object

Tenant-owned boundary payload. Structure varies by event_type. No public self-service payload schema catalogue is published in API 0.1.0. Treat payload shape as tenant-issued integration configuration, not Axiom-owned domain content.

object

Optional event metadata (routing hints, trace context)

Responses

Request samples

Content type
application/json
Example
{
  • "event_type": "external.event.received",
  • "source": "external-ingress",
  • "occurred_at": "2026-03-12T09:30:00Z",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Ledger

Double-entry accounting ledger — entries, transactions, account balances, reversals, integrity verification, and reconciliation. Supports as-of temporal queries with explanation traces.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Get account balance

Computes and returns the balance for a specific ledger account.

Supports point-in-time queries via the as_of parameter for historical balance lookups (as-was semantics per platform principle).

The response includes an explanation tree documenting the inputs, rule version, and computation method used.

Authorizations:
BearerAuth
path Parameters
code
required
string
Example: PREM-RCV-001

Account code to query (e.g. PREM-RCV-001, CLM-PAY-001)

query Parameters
as_of
string <date-time>
Example: as_of=2026-03-31T23:59:59Z

Point-in-time for the balance computation (ISO 8601). If omitted, returns the current balance.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Account balance computed successfully"
}

Create a ledger entry reversal

Creates a reversing entry for a previously posted ledger entry. The original entry's status transitions to reversed, and a new entry with the opposite entry_type and same amount is created.

This preserves the full audit trail rather than modifying or deleting the original entry (platform principle explainability).

Authorizations:
BearerAuth
path Parameters
entry_id
required
string <uuid>
Example: 50447be1-27bd-5a7a-b51c-edce72303e3f

Ledger entry UUID to reverse

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
reason
required
string

Reason for the reversal (required for audit trail)

posted_by
required
string

User or service authorising the reversal

entry_date
string <date-time>

Accounting date for the reversal (defaults to now)

Responses

Request samples

Content type
application/json
{
  • "reason": "Incorrect account code — premium posted to claims payable in error",
  • "posted_by": "hello@axiom.express",
  • "entry_date": "2026-04-01T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Verify ledger integrity

Runs integrity checks on the ledger to detect anomalies such as unbalanced transactions, orphaned entries, or sequence gaps.

This is a read-only operation that does not modify any data.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
optional
account_codes
Array of strings

Restrict verification to specific accounts (all if omitted)

date_from
string <date-time>

Start of verification period

date_to
string <date-time>

End of verification period

Responses

Request samples

Content type
application/json
{
  • "account_codes": [
    ],
  • "date_from": "2026-01-01T00:00:00Z",
  • "date_to": "2026-03-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List ledger entries for the tenant

Returns the tenant's ledger entries (keyset-ordered by entry_id ascending). Cursor-paginated under the governed contract: pass page[size] to bound the page and page[after] (an opaque cursor from a prior response's meta.next_cursor) to fetch the next page. Each entry is a double-entry posting line (governed contract); amounts are exact integer minor units.

Optional reference_id filter narrows the list to the postings recorded against a single source reference (e.g. a claim, policy, premium, or payment id). Absent = all entries for the tenant. The filter composes with the existing operating-tenant tenant-isolated scope; it never widens it.

Authorizations:
BearerAuth
query Parameters
reference_id
string

Optional filter — return only entries posted against this source reference id (reference_id, e.g. a claim / policy / premium / payment id). Absent = all entries for the tenant.

page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of entries to return (cursor page size, governed contract).

page[after]
string

Opaque cursor from a prior response's meta.next_cursor. Treat as opaque; do not construct or modify. Omit to fetch the first page.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Get corrections for a ledger entry

Retrieves the correction history for a specific ledger entry, including any reversals and re-postings.

Results sorted by created_at descending.

This supports the full audit trail and explainability requirements. — every correction is traceable back to the original entry.

Authorizations:
BearerAuth
path Parameters
entry_id
required
string <uuid>
Example: 50447be1-27bd-5a7a-b51c-edce72303e3f

Original ledger entry UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Party

Party management — individuals, organisations, brokers, agents, and providers. Parties are the actors in the insurance lifecycle (policyholders, claimants, beneficiaries, underwriters).

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List available party role types

Returns the catalogue of party role types available to the tenant. This is the permissible role_type vocabulary and metadata, not the set of role types currently in use. Use GET /v1/parties/role-types/usage for active assignment counts.

Runtime source: the tenant catalogue.role_types table. Bootstrap registry metadata may enrich known seed codes, but the tenant catalogue is the authority for which role_type values are available.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Role-type usage counts

Returns each role type that has at least one active (non-revoked) assignment for the tenant, with the count of holders. Role types in the registry with zero holders are not returned — pair with GET /v1/parties/role-types to render "available but unused" rows.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Register Party

Register a party identity record that may later carry roles. A party is the foundational Axiom primitive anchoring all relationships — to covers, policies, premiums, and events. This contract creates the identity record; role assignment is a separate operation.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
id
string <typed-prefix-id>

Optional client-provided identifier. If omitted, the server generates one.

party_type
required
string
Enum: "individual" "organization" "system"

Identity classification of the party. Contextual participation such as broker, provider, agent, adjuster, or assessor belongs to PartyRole.role_type.

external_id
string

External identifier from source_system. If supplied, source_system is required.

source_system
string (PartyExternalIDSourceSystem)
Enum: "unmapped" "kelevra_native" "broker_crm" "underwriter_pas"

Authoritative alpha registry for Party external identifier provenance. external_id and source_system form an exact lookup pair: callers must supply both or neither on list filters, and create/update must include source_system whenever external_id is supplied.

required
object

Party-specific data (name, contact details, identifiers, etc.)

created_by
string

Identifier of the user or service creating this party

status
string (PartyLifecycleStatus)
Enum: "active" "inactive" "suspended" "deceased" "merged" "opted_out"

Current Party lifecycle status.

  • active: Party can participate in transactions.
  • inactive: Party is no longer active.
  • suspended: Party is temporarily suspended pending review.
  • deceased: Natural-person Party is terminally deceased.
  • merged: Duplicate Party has been merged into merged_into_party_id and rejects later Party-scoped mutations.
  • opted_out: Party has opted out of new contact capture; historical contact reads remain available.
merged_into_party_id
string <typed-prefix-id>

Required when status is merged; rejected for non-merged statuses.

Responses

Request samples

Content type
application/json
{
  • "id": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "party_type": "individual",
  • "external_id": "BRK-000123",
  • "source_system": "broker_crm",
  • "attributes": {
    },
  • "created_by": "admin-user-001",
  • "status": "active",
  • "merged_into_party_id": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List parties

Retrieve a paginated list of parties for the tenant. Results are sorted by created_at descending. Sort order is not configurable.

Supports cursor-based pagination via page[size] and page[after] query parameters.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of parties to return in this cursor page.

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

source_system
string (PartyExternalIDSourceSystem)
Enum: "unmapped" "kelevra_native" "broker_crm" "underwriter_pas"
Example: source_system=broker_crm

Exact external identifier source-system filter. Must be supplied together with external_id; unknown values return 400 INVALID_REQUEST with accepted values in the error detail.

external_id
string

Exact external identifier filter. Must be supplied together with source_system so bare external_id cannot create ambiguous identity resolution.

q
string >= 3 characters

Free-text search term for Party lookup. The runtime rejects search terms shorter than three characters.

role
string

Tenant catalogue.role_types code filter for parties currently holding the role.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Get a party by ID

Retrieve a single party by its unique identifier, including any assigned roles. When as_of or recorded_at is supplied, the response replays the party from the immutable party history substrate using effective time and recorded time as-was semantics.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

query Parameters
as_of
string <date-time>

RFC3339 effective-time timestamp for party history replay. Defaults to current effective time.

recorded_at
string <date-time>

RFC3339 recorded-time timestamp for as-was party history replay. Defaults to the latest recorded version.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a party

Update an existing party's attributes and/or status. Attribute updates are merged with existing attributes (partial update semantics).

Side effects: updates the party record; emits an audit entry recording the change.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
external_id
string

Replacement external identifier. If supplied, the effective source_system must be known and valid.

source_system
string (PartyExternalIDSourceSystem)
Enum: "unmapped" "kelevra_native" "broker_crm" "underwriter_pas"

Authoritative alpha registry for Party external identifier provenance. external_id and source_system form an exact lookup pair: callers must supply both or neither on list filters, and create/update must include source_system whenever external_id is supplied.

object or null

Updated party-specific data. Merged with existing attributes.

status
string (PartyLifecycleStatus)
Enum: "active" "inactive" "suspended" "deceased" "merged" "opted_out"

Current Party lifecycle status.

  • active: Party can participate in transactions.
  • inactive: Party is no longer active.
  • suspended: Party is temporarily suspended pending review.
  • deceased: Natural-person Party is terminally deceased.
  • merged: Duplicate Party has been merged into merged_into_party_id and rejects later Party-scoped mutations.
  • opted_out: Party has opted out of new contact capture; historical contact reads remain available.
merged_into_party_id
string <typed-prefix-id>

Required when transitioning to status=merged; rejected for non-merged statuses.

updated_by
string

Identifier of the user or service performing the update

Responses

Request samples

Content type
application/json
{
  • "external_id": "BRK-000124",
  • "source_system": "broker_crm",
  • "attributes": {
    },
  • "status": "active",
  • "merged_into_party_id": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2",
  • "updated_by": "admin-user-002"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get roles assigned to a party

Retrieve all role assignments for a party across policies, claims, and other entities. Each role includes the context (entity type and ID) it is scoped to.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Assign a role to a party

Assign a new role to a party, scoped to a specific entity (e.g. a policy, claim, product, organization, policy item, or PartyGroup). For sponsor role assignments on a group context, the sponsor remains the Party role assignee and the PartyGroup is identified by entity_type=group/entity_id. Only one active sponsor is allowed per tenant/group context; duplicate active sponsor attempts return SPONSOR_CARDINALITY_VIOLATED (HTTP 409).

A party can hold multiple roles simultaneously, and the same party can hold different roles on different entities.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
role_type
required
string

Tenant catalogue.role_types code to assign. The server validates the code against the tenant catalogue, not a closed OpenAPI enum.

entity_type
required
string
Enum: "policy" "claim" "organization" "product" "policy_item" "group"

The type of entity this role is scoped to

entity_id
required
string <typed-prefix-id>

The identifier of the entity this role is scoped to

assigned_by
required
string

Identifier of the user or service assigning this role

object or null

Optional attributes for the role assignment

Responses

Request samples

Content type
application/json
{
  • "role_type": "string",
  • "entity_type": "policy",
  • "entity_id": "string",
  • "assigned_by": "string",
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List contacts for a party

Retrieve all contact records associated with a party. A party may have multiple contacts (e.g. personal email, work email, mobile, landline).

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Add a contact to a party

Create a new contact record for a party. Each contact includes an email address, phone number, and/or preferred contact method. Parties in opted_out status reject new contact capture with a 409 while historical contact reads remain available.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
email
string <email>

Email address

phone
string^\+?[1-9]\d{1,14}$

Phone number in E.164 format

preferred_contact_method
string
Enum: "email" "phone" "mail"

Preferred contact method

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "phone": "string",
  • "preferred_contact_method": "email"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a party contact

Update an existing contact record for a party.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

contactId
required
string <typed-prefix-id>

Unique contact identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
email
string <email>

Email address

phone
string^\+?[1-9]\d{1,14}$

Phone number in E.164 format

preferred_contact_method
string
Enum: "email" "phone" "mail"

Preferred contact method

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "phone": "string",
  • "preferred_contact_method": "email"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Delete a party contact

Remove a contact record from a party.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

contactId
required
string <typed-prefix-id>

Unique contact identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

List identity documents for a party

Retrieve all identity documents associated with a party (e.g. passport, national ID, tax number, company registration). Each identity has a verification status.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Add an identity document to a party

Register a new identity document for a party. The identity is created in "unverified" status and must be verified separately via the verify endpoint.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
identity_type
required
string

Type of identity document

identity_value
required
string

The identity document number or value

issuing_country
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code of issuing authority

expiry_date
string or null <date>

Expiry date of the identity document

Responses

Request samples

Content type
application/json
{
  • "identity_type": "string",
  • "identity_value": "string",
  • "issuing_country": "string",
  • "expiry_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Verify a party identity document

Mark an identity document as verified. This records the verification timestamp and transitions the identity status from "unverified" to "verified".

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

identityId
required
string <typed-prefix-id>

Unique identity document identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
verification_method
string

Method used for verification (e.g. manual, electronic, biometric)

verified_by
string

Identifier of the user or service performing verification

notes
string or null

Optional notes about the verification

Responses

Request samples

Content type
application/json
{
  • "verification_method": "string",
  • "verified_by": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List relationships for a party

Retrieve relationships for a party. The view parameter selects the response shape:

  • list (default): returns all active relationships as a flat array of relationship objects.
  • distribution_chain: traverses the distribution chain from this party, returning participants and an explanation tree (governed contract).

An unrecognised view value returns 400 INVALID_REQUEST under the governed contract.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

query Parameters
view
string
Default: "list"
Enum: "list" "distribution_chain"

Response view type. Unknown values return 400 INVALID_REQUEST under the governed contract.

as_of
string <date-time>

Point-in-time filter for relationships (ISO 8601). Defaults to current time.

relationship_type
string

Comma-separated tenant catalogue.relationship_types code filter.

max_depth
integer [ 1 .. 16 ]

Maximum traversal depth for view=distribution_chain (1-16). Ignored for view=list.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Create a relationship between two parties

Creates a directed relationship from the identified party (from_party_id) to another party (to_party_id). On success, returns 201 Created with the new relationship resource.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
to_party_id
required
string <typed-prefix-id>

Target party for the relationship

relationship_type
required
string

Tenant catalogue.relationship_types code. The server validates the code against the tenant catalogue, not a closed OpenAPI enum.

effective_from
string or null <date-time>

Relationship valid-from timestamp (ISO 8601). Defaults to now.

effective_to
string or null <date-time>

Relationship expiry timestamp. Null means open-ended.

object or null

Optional key-value metadata for the relationship

Responses

Request samples

Content type
application/json
{
  • "to_party_id": "string",
  • "relationship_type": "string",
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_to": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Delete (deactivate) a party relationship

Temporally deactivates a relationship by setting its effective_to to now. Idempotent — deactivating an already inactive relationship returns 204.

Body {"reason": "..."} is required (non-blank after trim) per . Blank reason returns 400 PARTY_DEACTIVATION_REASON_REQUIRED.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

relId
required
string <typed-prefix-id>

Unique relationship identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
reason
required
string

Non-blank rationale for the deactivation. Recorded on the audit record under the governed contract.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

List party groups containing this party

Inverse projection — returns the groups the given party is a member of as of as_of. Distinct from /v1/parties/:id/groups which returns Policy Group (governed contract) memberships.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: pty_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

List the policy-driven groups a party belongs to

Returns the transitive policy-group membership view for a party: the groups the party belongs to by virtue of a policy binding, each annotated with the via_policy_id that confers the membership. This is distinct from /v1/parties/{id}/party-groups (first-class, directly-assigned party-group memberships) — here membership is derived from policy participation, not a direct grouping assignment.

Point-in-time: pass as_of (RFC3339) to resolve membership as it stood at that instant; defaults to now.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
query Parameters
as_of
string <date-time>

Resolve membership as-of this instant (RFC3339). Defaults to now.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List payments for a party

Retrieves a paginated list of payments associated with a specific party. Returns only payments explicitly linked to the party via party_id. Payments without party linkage (null party_id) are excluded.

Results are sorted by created_at descending with id as a stable tie-breaker. Use page[size] and page[after] for pagination. Legacy limit and offset query parameters are rejected.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of payments to return

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Chronological audit feed for a party

Returns the per-party audit feed in chronological order (performed_at DESC). Each event carries governed contract actor attribution (actor_id / actor_type / actor_original_id) regardless of writer path. The reader merges persistence-managed records and application writes so the consumer sees a single shape.

Explanation enrichment fields (decision_id, rule_versions, inputs) are populated for rules-evaluation records only and empty otherwise (preview placeholder).

Use page[size] and page[after] for cursor pagination. Legacy limit and offset query parameters are rejected by the runtime.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
query Parameters
page[size]
integer [ 1 .. 200 ]
Default: 50

Maximum number of audit entries to return in this cursor page.

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Revoke a party role

Revoke an active role assignment from a Party. The role assignment remains part of the Party history and audit record; this operation changes its active status rather than deleting historical evidence.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

roleId
required
string <typed-prefix-id>

Party role assignment identifier to revoke.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get a party balance

Return the ledger-derived balance for a Party, optionally scoped by product, policy, cover, category, role, and as-of time. The response is computed from runtime ledger entries and is read-only.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

query Parameters
product_id
string <typed-prefix-id>

Limit the balance to entries associated with this product.

policy_id
string <typed-prefix-id>

Limit the balance to entries associated with this policy.

cover_id
string <typed-prefix-id>

Limit the balance to entries associated with this cover.

category
string

Limit the balance to a ledger category.

role
string

Limit the balance to a tenant catalogue.role_types code.

as_of
string <date-time>

Compute the balance as of this RFC3339 timestamp. Defaults to the current instant.

decompose
boolean
Default: false

Include balance computation explanation details when true.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Party Group

Composable party-grouping primitive under the governed contract. Groups can contain parties and other groups (polymorphic DAG membership), support static and dynamic (CEL-rule-driven) membership, and can hold roles in their own right without inheriting to member parties. Distinct from Policy Group (governed contract) which groups policies for cover application.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List party groups containing this party

Inverse projection — returns the groups the given party is a member of as of as_of. Distinct from /v1/parties/:id/groups which returns Policy Group (governed contract) memberships.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: pty_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Chronological audit feed for a party group

Returns the per-group audit feed in chronological order (performed_at DESC). party_groups + party_group_memberships have no persistence-managed records, so every row is generated by the application's NewAuditRecord path with a party.group_* operation code.

Response shape mirrors /v1/parties/{id}/audit — see that endpoint for the full AuditEntry field list.

Use page[size] and page[after] for cursor pagination. Legacy limit and offset query parameters are rejected by the runtime.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
query Parameters
page[size]
integer [ 1 .. 200 ]
Default: 50

Maximum number of audit entries to return in this cursor page.

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

List party groups

Returns party groups for the tenant with cursor pagination. Results are ordered by created_at descending with id as a stable tiebreaker. Supports a free-text search via q (3-character minimum under the governed contract).

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of party groups to return in this cursor page.

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

q
string >= 3 characters

Search across display_name, id, external_id (min 3 chars, governed contract)

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Create a party group

Creates a static or dynamic party group. For dynamic groups, membership_rule_id is required and must reference a rule of type party_grouping in the shared rules catalog (fail-loud; 400 on invalid reference). Idempotent via standard Idempotency-Key header.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
required
group_type
string
Enum: "static" "dynamic"

Defaults to static when omitted

display_name
required
string non-empty
description
string
external_id
string
id_namespace
string
Default: "tenant"
membership_rule_id
string

Required when group_type = dynamic

Responses

Request samples

Content type
application/json
{
  • "group_type": "static",
  • "display_name": "string",
  • "description": "string",
  • "external_id": "string",
  • "id_namespace": "tenant",
  • "membership_rule_id": "rule-party-age-over-18"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get a party group with its active members

Returns the group and its active memberships as of as_of (defaults to now). Members include both party-type and group-type (developer preview polymorphic DAG) — callers must discriminate on member_type.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update display_name / description / status

Partial update — only supplied fields are changed. Soft-delete is achieved via setting status to inactive here OR calling DELETE.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
required
display_name
string
description
string
status
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "description": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Soft delete (status → inactive)

Soft-delete — flips status to inactive. The group row and its memberships are preserved for audit under the governed contract. There is no hard delete.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Add a party or group as a member

Body must supply exactly one of party_id or group_id. Neither or both → 400. Cycle detection happens at read time (bounded traversal, governed contract) — writes do not block cyclic membership. Idempotent on (group, member_type, member_id) when a membership is already open.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
required
party_id
string <uuid>
group_id
string <uuid>
valid_from
string <date-time>

Defaults to now() server-side when omitted

Responses

Request samples

Content type
application/json
{
  • "party_id": "ba7116bd-f329-4d4b-adb9-b94174cc44e1",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "valid_from": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Close a member's open window (sets valid_to = now)

Idempotent — if no open membership exists, returns 204 without error. Does not hard-delete the membership row; the closed window is preserved for audit (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
partyId
required
string <typed-prefix-id>
Example: pty_01arz3ndektsv4rrffq69g5fav

Member id. The path parameter is named partyId for legacy reasons; the endpoint accepts both party-member-ids and group-member-ids (developer preview — any member_id regardless of type).

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

List all party members reachable via recursive expansion

Recursively walks the membership DAG and returns every party that is reachable — de-duplicated by party_id. Uses bounded traversal with a cycle guard (governed contract): diamonds are de-duped, cycles are short-circuited.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
max_depth
integer [ 0 .. 16 ]

BFS depth cap [1, 16]. Server returns 400 for out-of-range. 0 or omitted → default (4).

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List groups that transitively contain this group

BFS upward through the membership DAG up to max_depth.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
max_depth
integer [ 0 .. 16 ]
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

List groups transitively contained by this group

BFS downward through the membership DAG up to max_depth.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
query Parameters
as_of
string <date-time>
max_depth
integer [ 0 .. 16 ]
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Dry-run evaluate a party against a dynamic group's rule

Read-only evaluation — calls the membership-rule evaluator and returns is_member plus an explanation summary. Does NOT persist membership. Only valid for group_type = dynamic; static groups return 400. Classification: intentional_exception in the post-route manifest (POST that doesn't mutate).

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
required
party_id
required
string <uuid>
as_of
string <date-time>

Defaults to now() server-side

Responses

Request samples

Content type
application/json
{
  • "party_id": "ba7116bd-f329-4d4b-adb9-b94174cc44e1",
  • "as_of": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

List roles held directly by this group

Returns roles where this group is the assignee (assignee_type = group). under the governed contract there is NO automatic inheritance — these roles do not flow to member parties.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Assign a role to the group

Assigns a role with the group as assignee. Idempotent via Idempotency-Key.

For role_type=accepted_provider_network:

  • Assignee group must have composition_type=provider_network → 422 INVALID_ASSIGNMENT otherwise.
  • Context entity_type must be product → context entity_id must reference an existing product in the tenant → 404 PRODUCT_CONTEXT_NOT_FOUND if missing.
  • Overlapping active windows on the same (group, role_type, product) tuple return 409 NETWORK_ROLE_ALREADY_ACTIVE.
Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
required
role_type
required
string
Enum: "sponsor" "provider" "beneficiary" "accepted_provider_network"
required
object
effective_from
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "role_type": "accepted_provider_network",
  • "context": {
    },
  • "effective_from": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Revoke a role held by the group

Closes the role assignment with an optional reason supplied as a JSON body {reason: "..."}.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
roleId
required
string <typed-prefix-id>
Example: plg_01arz3ndektsv4rrffq69g5fav
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

Request Body schema: application/json
optional
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Payment

Payment processing — payment records and payment schedule management. Supports bank transfer, credit card, debit order, and other methods. Status: pending → processing → completed → failed → cancelled.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

List payments for a party

Retrieves a paginated list of payments associated with a specific party. Returns only payments explicitly linked to the party via party_id. Payments without party linkage (null party_id) are excluded.

Results are sorted by created_at descending with id as a stable tie-breaker. Use page[size] and page[after] for pagination. Legacy limit and offset query parameters are rejected.

Authorizations:
BearerAuth
path Parameters
id
required
string <typed-prefix-id>

Unique party identifier

query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of payments to return

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

List payments

Retrieves a cursor-paginated list of payments for the current tenant.

Results are sorted by created_at descending with id as a stable tie-breaker.

Use page[size] and page[after] for pagination. Legacy limit and offset query parameters are rejected.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20
Example: page[size]=20

Maximum number of items to return (default 20, max 100)

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success",
  • "message": "Payments retrieved successfully"
}

Create a payment

Creates a new payment record in pending status.

The payment is not processed immediately. Use the POST /v1/payments/{id}/process endpoint to initiate processing.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
required
object

Payment amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty.

payment_method
required
string (PaymentMethod)
Enum: "bank_transfer" "credit_card" "debit_order" "cash" "cheque"

Supported payment methods:

  • bank_transfer — Electronic funds transfer (EFT) or wire transfer
  • credit_card — Credit card payment via payment gateway
  • debit_order — Recurring debit order (direct debit) from bank account
  • cash — Cash payment (recorded manually, typically at branch)
  • cheque — Cheque payment (subject to clearing period)
description
string or null

Human-readable description of the payment purpose

reference_id
string or null <uuid>

Reference to the associated resource (premium, claim, etc.)

reference_type
string or null

Type of the referenced resource

party_id
string or null <uuid>

Reference to the party associated with this payment. Must be a valid party ID within the tenant.

object or null

Extensible key-value metadata

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "payment_method": "bank_transfer",
  • "description": "Annual premium — liability professional indemnity POL-2026-00789",
  • "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7",
  • "reference_type": "premium",
  • "party_id": "07805e66-69d7-5b42-a978-32729404b560",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment created successfully"
}

Get a payment by ID

Retrieves a single payment by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a payment

Updates a payment record. Only payments in pending status can be updated.

Fields that can be updated: amount, currency, payment_method, description, reference_id, reference_type, metadata.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
object

Updated payment amount (exact integer minor units + lowercase ISO-4217 currency code).

payment_method
string (PaymentMethod)
Enum: "bank_transfer" "credit_card" "debit_order" "cash" "cheque"

Supported payment methods:

  • bank_transfer — Electronic funds transfer (EFT) or wire transfer
  • credit_card — Credit card payment via payment gateway
  • debit_order — Recurring debit order (direct debit) from bank account
  • cash — Cash payment (recorded manually, typically at branch)
  • cheque — Cheque payment (subject to clearing period)
description
string or null

Updated human-readable description

reference_id
string or null <uuid>

Updated reference to associated resource

reference_type
string or null

Updated type of referenced resource

object or null

Updated extensible metadata

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "payment_method": "debit_order",
  • "description": "Adjusted monthly premium — motor comprehensive policy POL-2026-00123",
  • "reference_id": "97c1ff22-6e4f-4821-b1d3-5236781d37b8",
  • "reference_type": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Process a payment

Initiates processing for a pending payment.

Transitions the payment through the lifecycle: pending -> processing -> completed (or failed).

This is an asynchronous operation. The response confirms the payment has been submitted for processing. Poll the payment status or use webhooks to track completion.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment submitted for processing"
}

Cancel a payment

Cancels a payment. Only payments in pending or processing status can be cancelled.

Transitions the payment to cancelled status. This action cannot be undone.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment cancelled successfully"
}

List payment schedules

Retrieves a cursor-paginated list of payment schedules for the current tenant.

Results are derived from aggregate Premium rows and sorted by effective_date descending with id as a stable tie-breaker.

Payment schedules define recurring cadence obligations tied to policies (e.g. monthly debit orders for motor premiums, quarterly bank transfers for property cover). The list surface reports cadence definitions; per- instalment paid/overdue state belongs to the payment settlement surface.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20
Example: page[size]=20

Maximum number of payment schedules to return in this page.

page[after]
string

Opaque cursor returned as meta.next_cursor from the previous page. Do not construct or modify this value.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success",
  • "message": "Payment schedules retrieved successfully"
}

Create a payment schedule

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the payment-schedule creation workflow is implemented.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
policy_id
required
string <uuid>

Reference to the policy this schedule services

frequency
required
string (PaymentFrequency)
Enum: "monthly" "quarterly" "half_yearly" "annual"

Payment schedule frequency:

  • monthly — Payment due every month
  • quarterly — Payment due every 3 months
  • half_yearly — Payment due every 6 months
  • annual — Payment due once per year
amount
required
integer <int64> >= 0

Scheduled payment amount per period in the smallest currency unit (e.g. cents). Exact integer representation.

currency
required
string^[A-Z]{3}$

ISO 4217 currency code

next_due_date
required
string <date>

First scheduled payment date

Responses

Request samples

Content type
application/json
{
  • "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd",
  • "frequency": "half_yearly",
  • "amount": 420000,
  • "currency": "EUR",
  • "next_due_date": "2026-06-01"
}

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Get a payment schedule by ID

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the payment-schedule detail workflow is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Pause a payment schedule

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the payment-schedule state machine is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

Resume a paused payment schedule

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the payment-schedule state machine is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
Example
{
  • "errors": [
    ]
}

List invoices with cursor pagination

Retrieves a paginated list of invoices for the current tenant using cursor-based pagination under the governed contract.

Legacy offset-based pagination (limit/offset query params) is rejected with 400 LEGACY_PAGINATION.

Results sorted by created_at descending.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 25

Maximum number of items to return (default 25, max 100)

page[after]
string

Cursor for the next page (invoice ID from previous response)

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Get a single invoice by ID

Retrieves a single invoice by its unique identifier. Returns 404 for unknown IDs or cross-tenant access attempts.

Authorizations:
BearerAuth
path Parameters
id
required
string

Invoice identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Finalize an invoice

Finalizes a draft invoice, making it immutable. Requires actor attribution headers under the governed contract.

Authorizations:
BearerAuth
path Parameters
id
required
string

Invoice identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string

Request correlation ID for tracing

X-Actor-ID
required
string

Actor identifier (governed contract)

X-Actor-Type
required
string
Enum: "human" "service" "agent"

Actor type (governed contract)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Close a billing cycle

Closes a billing cycle for the specified period, generating an invoice. Requires actor attribution headers under the governed contract.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string

Request correlation ID for tracing

X-Actor-ID
required
string

Actor identifier (governed contract)

X-Actor-Type
required
string
Enum: "human" "service" "agent"

Actor type (governed contract)

Request Body schema: application/json
required
period_start
required
string <date-time>

Start of the billing period (RFC3339)

period_end
required
string <date-time>

End of the billing period (RFC3339)

idempotency_key
string

Optional idempotency key for deduplication

Responses

Request samples

Content type
application/json
{
  • "period_start": "2026-03-01T00:00:00Z",
  • "period_end": "2026-03-31T23:59:59Z",
  • "idempotency_key": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Policy

Policy lifecycle — creation, versioning, endorsements, and status transitions. A policy binds a product to parties with specific terms and coverage dates. Status: draft → active → suspended → cancelled → expired → lapsed.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Initiate a policy replacement

Starts a replacement workflow that supersedes one or more existing policies with a replacement policy. Returns the initial workflow state including the allowed transitions from the starting step.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
policy_id
required
string

The replacement policy id (typed-prefix wire form).

existing_policy_ids
required
Array of strings

Policies being superseded by this replacement.

jurisdiction_code
required
string

ISO 3166-1 alpha-2 jurisdiction code (lowercase).

required
object (replacementActor)
reason
required
string

Human-intelligible justification (audit trail).

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

object

Optional caller-supplied metadata.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j1234567890abcdefghijk",
  • "existing_policy_ids": [
    ],
  • "jurisdiction_code": "za",
  • "actor": {
    },
  • "reason": "Customer requested upgrade to comprehensive cover",
  • "occurred_at": "2026-06-02T12:00:00Z"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a replacement workflow

Fetch the current state of a replacement workflow by id.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Advance a replacement workflow

Advances the workflow to the next step, supplying the evidence payload required by the current step. Optimistic-concurrency via version.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
required
object (replacementActor)
reason
required
string

Human-intelligible justification for the advance.

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

required
object

Step-specific evidence required to advance.

version
required
integer

Optimistic-concurrency version of the workflow being advanced.

Responses

Request samples

Content type
application/json
{
  • "actor": {
    },
  • "reason": "Replacement disclosure acknowledged",
  • "occurred_at": "2026-06-02T12:05:00Z",
  • "evidence_payload": {
    },
  • "version": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cancel a replacement workflow

Cancels an in-flight replacement workflow. Optimistic-concurrency via version.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
required
object (replacementActor)
reason
required
string

Human-intelligible cancellation justification.

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

version
required
integer

Optimistic-concurrency version of the workflow being cancelled.

Responses

Request samples

Content type
application/json
{
  • "actor": {
    },
  • "reason": "Customer withdrew request",
  • "occurred_at": "2026-06-02T12:10:00Z",
  • "version": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get replacement evidence

Returns the evidence collected per step for a replacement workflow.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract).

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Apply Proration Adjustment

Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

Optional premium identity in wire form when the decision affects a known premium.

product_id
required
string

Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "premium_id": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "product_id": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "proration_intent": "mid_year_join",
  • "reason": "string",
  • "correction_of_decision_id": "e12d0bbe-ce81-4547-b5ce-7b1ddd242520",
  • "affected": {
    },
  • "effective_times": {
    },
  • "inputs": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Create a new policy

Issue a new insurance policy under an active product. The policy is created in "draft" status by default. At least one party must be assigned (typically the policyholder). Draft policies are not endorsement-eligible; use POST /v1/policies/bind to create an active, endorsement-eligible policy.

The product must be in "active" status before policies can be issued against it. The effective date must not be in the past (backdating requires special permissions).

Side effects: persists the policy in draft status with assigned parties; emits an audit entry recording the creation.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
product_id
required
string <uuid>

Identifier of the product to issue the policy under

effective_date
required
string <date>

Date from which the policy provides coverage

expiry_date
required
string <date>

Date on which the policy coverage ends

object or null

Policy-specific data

required
Array of objects (PolicyPartyRequest) non-empty

Parties to assign to the policy (at least one required)

created_by
string

Identifier of the user or service creating this policy

binding_mode
string
Default: "individual"
Enum: "individual" "group"

Policy binding mode. When omitted, defaults to "individual" for backward compatibility. Set to "group" for master policy inception (group/employer/family).

object or null

Required when binding_mode=group; must be absent for individual policies. Describes the group contract metadata.

Responses

Request samples

Content type
application/json
Example
{
  • "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b",
  • "effective_date": "2026-04-01",
  • "expiry_date": "2027-03-31",
  • "attributes": {
    },
  • "parties": [
    ],
  • "created_by": "agent-user-012"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy created successfully"
}

List policies

Retrieve a cursor-paginated list of policies for the tenant. Results are sorted by most-recently-recorded first. Sort order is not configurable. Legacy limit and offset query parameters are rejected.

Returns policies across all statuses (draft, quoted, bound, active, lapsed, cancelled, expired).

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of policies to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

party_id
string

Optional filter — return only policies the party is bound to in any role (the party appears in policy.parties). Accepts the canonical typed-prefix party id (pty_…, governed contract). A malformed value returns 400. Absent = all policies for the tenant (current behaviour). Composes with the existing operating-tenant tenant-isolated scope; never widens it.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Bind Policy

Bind parties to covers through an active policy version. This contract is the primary policy-creation operation — it reads party and product/cover context, creates an immutable policy version, and conditionally triggers premium effects. Requires idempotency: callers must supply an idempotency key to prevent duplicate policy creation on retry.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
quote_id
string

Quote identifier for quote-backed bind. Mutually exclusive with inline fields (product_id, effective_date, expiry_date).

product_id
string

Product identifier for inline bind. Required when quote_id is not provided.

effective_date
string <date-time>

RFC3339 timestamp for policy activation. Required for inline bind (when quote_id is not provided).

expiry_date
string <date-time>

RFC3339 timestamp for policy expiry. Required for inline bind (when quote_id is not provided).

object
required
Array of objects non-empty
payment_method
required
string
bound_by
required
string
binding_mode
string
Default: "individual"
Enum: "individual" "group"

Policy binding mode. Defaults to "individual" for backward compatibility. Set to "group" for master policy inception.

object or null

Required when binding_mode=group; must be absent for individual.

Responses

Request samples

Content type
application/json
{
  • "quote_id": "string",
  • "product_id": "string",
  • "effective_date": "2019-08-24T14:15:22Z",
  • "expiry_date": "2019-08-24T14:15:22Z",
  • "underwriting_data": { },
  • "parties": [
    ],
  • "payment_method": "string",
  • "bound_by": "string",
  • "binding_mode": "individual",
  • "group_context": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get a policy by ID

Retrieve a single policy with its full details including assigned parties and premium schedule.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Create a new policy version

Create a new version snapshot of the policy. Policy versions provide an immutable record of the policy state at each point in time, supporting "as-was" semantics required for claims adjudication and regulatory reporting.

Each version captures the complete policy state including attributes, parties, and coverage details at the time of creation.

Side effects: not yet implemented. Returns 501.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
effective_date
required
string <date>

Date from which this version takes effect

reason
string

Reason for creating a new version

created_by
string

Identifier of the user or service creating this version

Responses

Request samples

Content type
application/json
Example
{
  • "effective_date": "2026-06-01",
  • "reason": "Mid-term adjustment — sum insured increase from 250,000 to 300,000",
  • "created_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy version created successfully"
}

List policy version snapshots

Return every immutable version snapshot for the policy, ordered by version_number ascending.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Issue a draft policy

Transition a policy from draft to bound status. The policy must have at least one party with the policyholder role assigned.

Side effects: persists the status change and emits an audit entry with operation code policy.issue in a single transaction.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
issued_by
required
string

Identifier of the user or service issuing the policy

notes
string

Optional notes for the issue action

Responses

Request samples

Content type
application/json
{
  • "issued_by": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy issued successfully"
}

Activate a bound policy

Transition a policy from bound to active status. The policy's effective date must be in the past or present (effective_date <= now).

Side effects: persists the status change and emits an audit entry with operation code policy.activate in a single transaction.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
activated_by
required
string

Identifier of the user or service activating the policy

Responses

Request samples

Content type
application/json
{
  • "activated_by": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy activated successfully"
}

Create a policy endorsement

Submit an endorsement (mid-term adjustment) to an active policy. Endorsements record structured changes to the policy terms, coverage, or parties. The policy must be in active status; endorsing a draft or other non-active policy returns HTTP 422 with code INVALID_STATE_TRANSITION.

Each endorsement receives a sequential number within the policy (END-001, END-002, etc.) and triggers the creation of a new policy version when applied.

Side effects: creates a new immutable policy version and persists party-role changes when change_type=parties. Emits an audit entry when audit is configured.

Common endorsement types:

  • amendment: Modify existing terms (e.g. change address, increase sum insured)
  • addition: Add new coverage or parties
  • deletion: Remove coverage or parties
  • correction: Fix data entry errors
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
change_type
required
string
Enum: "parties" "coverages" "terms" "premium"

Classification of the endorsement change

description
required
string

Human-readable description of the changes

Array of objects

New parties to add (for change_type 'parties')

object or null

Structured representation of attribute changes

endorsed_by
required
string

Identifier of the user or process creating the endorsement

effective_at
string <date-time>

Effective timestamp for party endorsements (change_type=parties). Must not be retroactive. Required when change_type=parties.

Array of objects

Party mutations for change_type=parties endorsements. Each entry specifies an operation (add/revoke/replace), party_id, and role.

Responses

Request samples

Content type
application/json
Example
{
  • "change_type": "coverages",
  • "description": "Increase vehicle insured value following market revaluation",
  • "updated_attributes": {
    },
  • "endorsed_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Endorsement created successfully"
}

List policy endorsements

Return the policy's endorsements, ordered by version_number ascending. Endorsements are stored as policy version snapshots (no separate entity); this list is the policy's versions filtered to version_type == endorsement.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Get member certificate projection

Retrieve a read-only certificate of insurance for a specific member on a group policy. Resolves the effective policy version and active roles at the as_of timestamp (defaults to now). Returns the master policy_id, party_id, role list, effectivity window, and pinned version_id.

No persistence side effects — this is a pure read projection.

Returns 404 if the party is unknown or inactive at the given as_of time.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

party_id
required
string

Identifier of the member party

query Parameters
as_of
string <date-time>

Point-in-time for certificate resolution (defaults to now)

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Certificate retrieved successfully"
}

Create a new quote

Creates a persisted premium calculation (quote) with a 30-minute TTL. Exactly one of pricing_snapshot_id, products, or product_id must be provided.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
pricing_snapshot_id
string

Reference to a prior rate result snapshot (mutually exclusive with products)

Array of objects

Inline product + risk_profile pairs (mutually exclusive with pricing_snapshot_id)

product_id
string

Legacy single-product shorthand (backward compatible)

effective_date
required
string <date>
expiry_date
required
string <date>
object
covers_selected
Array of strings
Default: []
comparison_ref
string

Links comparison sets for quote comparison

supersedes
string

Quote ID this quote supersedes

Array of objects (QuoteParty)

Party snapshot for bind-time matching

Responses

Request samples

Content type
application/json
{
  • "pricing_snapshot_id": "string",
  • "products": [
    ],
  • "product_id": "string",
  • "effective_date": "2026-04-01",
  • "expiry_date": "2027-04-01",
  • "underwriting_data": {
    },
  • "covers_selected": [ ],
  • "comparison_ref": "string",
  • "supersedes": "string",
  • "parties": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

List quotes by comparison reference

Returns all quotes for a given comparison_ref, ordered by created_at DESC. Tenant-scoped to prevent cross-tenant leakage.

Authorizations:
BearerAuth
query Parameters
comparison_ref
required
string

Comparison reference to filter quotes

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "telemetry": {
    }
}

Retrieve a quote by ID

Returns the persisted quote if active. Returns 404 for unknown IDs (including cross-tenant lookups) and 410 Gone for expired quotes.

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

Approve a quote (indicative to firm)

Transitions a quote from indicative to firm status. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

Decline a quote

Transitions a quote to declined status. Requires a reason_code. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
reason_code
required
string

Machine-readable reason for declining the quote

Responses

Request samples

Content type
application/json
{
  • "reason_code": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

Bind a firm quote to create a policy

Binds a firm quote, creating a policy, premium allocation, ledger entries, and explanation tree. Only firm quotes can be bound. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Idempotency-Key
required
string

Idempotency key for bind operations (required under the governed contract)

Request Body schema: application/json
required
payment_method
required
string
bound_by
required
string
Array of objects (QuoteParty)

Bind-time parties (must match quote snapshot if provided)

Responses

Request samples

Content type
application/json
{
  • "payment_method": "string",
  • "bound_by": "string",
  • "parties": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "telemetry": {
    }
}

Get quote supersession chain

Returns the full supersession chain for a quote, ordered oldest-first. Walks backward through supersedes_quote_id links and reverses.

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "telemetry": {
    }
}

Get Proration Balance

Read a tenant-owned policy-scoped balance derived from accepted proration decision components for implemented governed contract proration consumers. Slice 1 supports fund and earning balances; treaty-scoped reinsurance balances fail closed until governed treaty authority exists.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

consumer
required
string
Enum: "fund_balance" "earning_balance" "reinsurance_balance"

Implemented proration balance consumer. reinsurance_balance is an accepted fail-closed value until governed treaty authority exists.

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

Fund account code, required for fund_balance unless account_code is supplied.

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

Earning period key, required for earning_balance unless account_code is supplied.

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Premium

Premium management — billing records and premium calculation engine. Includes standalone premium CRUD and product-based calculation with adjustments and commission breakdowns.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Apply Proration Adjustment

Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

Optional premium identity in wire form when the decision affects a known premium.

product_id
required
string

Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "premium_id": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "product_id": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1",
  • "proration_intent": "mid_year_join",
  • "reason": "string",
  • "correction_of_decision_id": "e12d0bbe-ce81-4547-b5ce-7b1ddd242520",
  • "affected": {
    },
  • "effective_times": {
    },
  • "inputs": { }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Simulate an allocation breakdown

Validates a proposed allocation breakdown without persisting it. Accepts only simulation_preview as trigger. Returns 422 for semantic validation failures (sum mismatch, missing rule_id, invalid inputs).

Each operation in the request specifies a benefit change (add, remove, change) with proposed allocation values in allocation_inputs.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Policy identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List temporal allocation history for a policy

Returns cursor-paginated temporal allocation snapshots for all premiums in a policy. Ordered by effective_from DESC, created_at DESC, premium_id ASC. Uses half-open [effective_from, effective_to) temporal semantics under the governed contract.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Policy identifier

query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Number of resources per page

page[after]
string

Cursor for forward pagination (allocation ID)

page[before]
string

Cursor for backward pagination (allocation ID)

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List premiums

Retrieve a paginated list of aggregate premium records for the operating tenant (one Premium per policy, the contract model). Cursor-paginated with page[size] default 20 / max 100 and opaque page[after] cursors. Legacy limit and offset query parameters are rejected.

The policy_id / party_id filter parameters are validated fail-loud (a malformed typed-prefix value returns 400, governed contract); they compose with the operating-tenant tenant-isolated scope, never widen it.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of premiums to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

policy_id
string

Optional filter — return only premiums for this policy. Accepts the canonical typed-prefix policy id (pol_…, governed contract). A malformed value returns 400. Absent = all premiums for the tenant. Composes with the existing operating-tenant tenant-isolated scope; never widens it.

party_id
string

Optional filter — return only premiums owed by this party (the premium debtor / policyholder). Accepts the canonical typed-prefix party id (pty_…, governed contract). A malformed value returns 400. Absent = all premiums for the tenant. Composes with the existing operating-tenant tenant-isolated scope; never widens it.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Create a premium record

Persist a new aggregate premium (inflow-obligation) record for a policy and return it with 201 Created. Exactly one Premium exists per policy (the (tenant context, policy_id) uniqueness constraint, the contract model) — a create for a policy that already has a premium fails loud with 409 Conflict.

This persists a manually-entered / imported inflow-obligation record at status=draft. It is NOT a rated premium decision — the rated path is POST /v1/premiums/calculate, which evaluates versioned CEL rules and emits an explanation tree. A draft obligation carries no rating decision to explain (platform principle untouched).

The premium is scoped to the operating tenant — tenant context is taken from the tenant-context, never the request body. Intentional defaults applied on create (documented, not silent): status=draft, premium_type defaults to initial, and an unrated draft sets base_premium = net_premium = final_premium = amount.amount_minor (no discounts/commission yet, contract rule).

Idempotent via the Idempotency-Key header: same key + same body returns the original 201; same key + different body returns 409.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
policy_id
required
string

Reference to the policy this premium belongs to, in the canonical typed-prefix form (pol_…, governed contract). A bare UUID is also accepted. A malformed value returns 400.

required
object

Premium amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty.

premium_type
string

Optional classifier on the aggregate premium (defaults to initial when omitted, contract rule). E.g. initial, renewal, endorsement, adjustment.

party_id
string

Optional reference to the party who owes this premium, in the canonical typed-prefix form (pty_…, governed contract). A bare UUID is also accepted. A malformed value returns 400.

Responses

Request samples

Content type
application/json
Example
{
  • "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a",
  • "amount": {
    },
  • "premium_type": "initial"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Premium created successfully"
}

Get a premium by ID

Retrieve a single premium record by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique premium identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Get allocation snapshot for a premium

Returns the benefit-level allocation breakdown for a premium at a point in time. Uses half-open temporal semantics under the governed contract.

Each allocation row includes benefit_id, amount (Money object with amount_minor + currency_code), allocation_percentage_bps, allocation_basis, calculation_version, and allocation_rule_id (when basis is rule_based).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Premium identifier

query Parameters
as_of
string <date-time>

Point-in-time for temporal query (RFC3339). Defaults to now.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Get Proration Balance

Read a tenant-owned policy-scoped balance derived from accepted proration decision components for implemented governed contract proration consumers. Slice 1 supports fund and earning balances; treaty-scoped reinsurance balances fail closed until governed treaty authority exists.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

consumer
required
string
Enum: "fund_balance" "earning_balance" "reinsurance_balance"

Implemented proration balance consumer. reinsurance_balance is an accepted fail-closed value until governed treaty authority exists.

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

Fund account code, required for fund_balance unless account_code is supplied.

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

Earning period key, required for earning_balance unless account_code is supplied.

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Product

Insurance product catalogue — product definitions, covers, cover provisions, terms, pricing rules, and commissions. Products are templates from which policies are created. Supports motor, property, health, life, liability, and more.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Create a new insurance product

Create a product definition in the catalogue. Products define the coverage template from which policies are issued. A product includes coverage sections (covers), configurable terms, pricing rules, and commission structures.

Products are created in "draft" status and must be explicitly activated before policies can be issued against them.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
product_code
required
string

Human-readable product code (must be unique within the tenant)

name
required
string

Display name of the product

type
required
string

Product classification

description
required
string

Detailed description of the product

currency
required
string^[A-Z]{3}$

ISO 4217 currency code

required
object

Product configuration including required base_premium. governed contract: missing base_premium is an error, not a default.

required
Array of objects (AddCoverRequest) non-empty

Required: at least one coverage section (governed contract: no silent defaults)

required
Array of objects (ProductTermCreate) non-empty

Required: at least one configurable term (governed contract: no silent defaults). Create-shaped: no server-minted term id (governed contract / governed contract).

Responses

Request samples

Content type
application/json
Example
{
  • "product_code": "MOTOR-TPL-2026",
  • "name": "Motor Third-Party Liability",
  • "type": "motor",
  • "description": "Mandatory third-party liability cover for motor vehicles registered in the United Kingdom",
  • "currency": "GBP",
  • "attributes": {
    },
  • "covers": [
    ],
  • "terms": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Product created successfully"
}

List products

Retrieve a paginated list of products in the tenant's catalogue. Results are sorted by recorded_at descending with a stable cursor tiebreaker. Sort order is not configurable.

Both draft and active products are returned. Use the status field to filter if needed (client-side filtering).

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of products to return in this cursor page

page[after]
string

Opaque product cursor from the previous response meta.next_cursor

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success"
}

Get a product by ID

Retrieve a single product with its full configuration including covers, terms, pricing rules, and commission structures.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

Update a product

Update an existing product's metadata, attributes, or status. Products can be transitioned from "draft" to "active" status via this endpoint.

Updating an active product creates a new version. Existing policies issued under previous versions are not affected.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated display name

description
string

Updated description

status
string
Enum: "draft" "active"

Updated product status

object or null

Updated extensible attributes (merged with existing)

Responses

Request samples

Content type
application/json
Example
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Product updated successfully"
}

Get coverage sections for a product

Retrieve all coverage sections (covers) defined for a product. Each cover includes its sum insured, deductible, type (basic/optional/rider), and any associated cover provision definitions and terms.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success"
}

Add a coverage section (cover) to a product

CRS-3: add a cover to a draft product. The cover may carry nested cover_items (each with terms) and cover-level cover_terms, persisted as the full canonical cover.* row graph in one atomic transaction. Money boundaries are exact integer minor units with a lowercase ISO-4217 currency; a monetary boundary missing its currency is rejected (422). Co-insurance panel splits (basis points) must sum to 10000bp (100%) or the request is rejected (422).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string

Short code for this coverage section

name
required
string

Display name

description
string

Detailed description of coverage

type
required
string
Enum: "basic" "optional" "rider"

Coverage type within the product

sum_insured
integer or null <int64>

Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.

deductible
integer or null <int64>

Excess amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.

object or null

Extensible attributes

Array of objects or null (AddCoverItemRequest)

CRS-3: nested cover items, each with its own terms. Persisted as the full canonical cover.* row graph in one atomic transaction.

Array of objects or null (AddCoverTermRequest)

CRS-3: nested cover-level terms (conditions, limits, exclusions).

Responses

Request samples

Content type
application/json
{
  • "code": "TPL-BODILY",
  • "name": "Third-Party Bodily Injury",
  • "description": "Covers liability for bodily injury to third parties arising from vehicle use",
  • "type": "basic",
  • "sum_insured": 100000000,
  • "deductible": 50000,
  • "attributes": { },
  • "cover_items": [
    ],
  • "cover_terms": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Bind a product to a ruleset version for a pipeline stage

Creates or supersedes the active product↔ruleset binding for the given ruleset_type (pipeline stage). under the governed contract a single product carries one binding per (tenant context, product_id, ruleset_type, effective_from); binding a different ruleset_type does NOT close the prior stage's active row — supersession is per-stage.

ruleset_type is REQUIRED and must be in the canonical allowlist (see 400 INVALID_RULESET_TYPE body for the accepted set). Earlier runtime behaviour silently defaulted the field to claims_assessment at the persistence boundary. The current contract rejects missing or unknown values at the HTTP boundary with the accepted set listed in the error body.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
ruleset_id
required
string <uuid>

ID of the ruleset to bind to the product

ruleset_type
required
string

Pipeline stage the binding satisfies. Must be in the canonical allowlist; see 400 INVALID_RULESET_TYPE response for the full set.

ruleset_version
required
integer >= 1

Version number of the bound ruleset

effective_from
required
string <date>

Date this binding becomes active (YYYY-MM-DD)

Responses

Request samples

Content type
application/json
{
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "ruleset_type": "premium_rating",
  • "ruleset_version": 1,
  • "effective_from": "2026-01-01"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}

List product↔ruleset bindings (active and historical)

Returns the binding history for a product in deterministic order (effective_from DESC, created_at DESC, id DESC). Each item includes ruleset_type so callers can distinguish stages without re-querying.

Optional ?ruleset_type= filter narrows the response to a single stage. Unknown values are rejected with 400 INVALID_RULESET_TYPE (no silent empty-list).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

query Parameters
ruleset_type
string

Filter by pipeline stage; must be in the canonical allowlist

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success"
}

Activate a draft product

Transition a product from draft to active status. The product must have at least one cover and defined terms (with explicit validation bounds) before activation.

This is a status-only transition: it does NOT re-persist the product's cover graph, so it never collides on existing covers (unlike a full PUT update). Side effects: persists the status change and emits a formal activation explanation tree (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
activated_by
string
Deprecated

Retired compatibility field. Product activation attribution is derived from the authenticated actor context and this value is ignored.

Responses

Request samples

Content type
application/json
{
  • "activated_by": "usr_3f8a"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Chronological audit feed for a product

Returns the per-product audit feed in descending performed-at order. The feed is scoped to the admitted tenant context, verifies that the product exists before reading audit rows, and never returns a silent empty feed for an unknown product identifier.

Use limit and offset for the current bounded alpha page contract. The runtime default is 50 rows from offset 0.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

Maximum number of audit entries to return.

offset
integer >= 0
Default: 0

Zero-based audit entry offset.

header Parameters
X-Tenant-Context
required
string

Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "message": "string",
  • "meta": {
    },
  • "links": { },
  • "telemetry": { }
}

Report

Report generation and export (PDF, CSV).

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Export a report

Generates and exports a report in the requested format (PDF or CSV).

Supported report types:

  • premium_collection — Premium collection summary by product and period
  • claims_register — Claims register with status, amounts, and settlement details
  • loss_ratio — Loss ratio analysis by product line
  • policy_register — Policy register with coverage and premium details
  • reconciliation — Ledger reconciliation report
  • commission_statement — Broker commission statement

The response is the report file itself (binary content), not a JSON envelope.

Authorizations:
BearerAuth
query Parameters
type
required
string
Enum: "premium_collection" "claims_register" "loss_ratio" "policy_register" "reconciliation" "commission_statement"
Example: type=premium_collection

Report type to generate

format
required
string
Enum: "pdf" "csv"
Example: format=pdf

Output format for the report

date_from
string <date>
Example: date_from=2026-01-01

Start date for the report period (inclusive, ISO 8601 date)

date_to
string <date>
Example: date_to=2026-03-31

End date for the report period (inclusive, ISO 8601 date)

product_code
string
Example: product_code=motor-comprehensive

Filter report to a specific product code

currency
string^[A-Z]{3}$
Example: currency=USD

Currency for monetary amounts (defaults to tenant base currency)

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Ruleset

Business rules engine — rulesets, rules, testing, and deployment. Rules are data.: explicit, versioned, deterministic, auditable. Supports CEL expressions, conditions, and actions.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Create a ruleset

Creates a new ruleset in draft status.

Rulesets are versioned containers of business rules that govern domain rule lanes such as underwriting, pricing, claims assessment, document completeness, or discount composition. Rules are data. — explicit, versioned, deterministic, and auditable.

Optionally specify a base_ruleset code to inherit rules from an existing ruleset as a starting point.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string

Machine-readable ruleset code (must be unique within the tenant)

name
required
string

Human-readable ruleset name

entity_type
required
string
Enum: "claims" "underwriting" "pricing" "claims_assessment" "document_completeness" "discount"

Runtime rule lane this ruleset governs

description
required
string

Detailed description of the ruleset purpose

object or null

Optional metadata (jurisdiction, product line, etc.)

base_ruleset
string or null

Code of an existing ruleset to use as a template. The new ruleset inherits rules from the base, which can then be overridden or extended.

Responses

Request samples

Content type
application/json
{
  • "code": "health-gap-ng-v1",
  • "name": "Nigeria Health Gap Cover",
  • "entity_type": "pricing",
  • "description": "Pricing rules for health gap cover in Nigeria",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Ruleset created successfully"
}

List rulesets

Retrieves a paginated list of rulesets for the current tenant.

Results are sorted by recorded_at descending with the ruleset id as a stable cursor tiebreaker. Legacy limit and offset query parameters are rejected; use page[size] and page[after].

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20
Example: page[size]=20

Maximum number of items to return (default 20, max 100)

page[after]
string
Example: page[after]=eyJyZWNvcmRlZF9hdCI6IjIwMjYtMDgtMTVUMTI6MDA6MDBaIiwiaWQiOiJiMWMyZDNlNC1mNWE2LTc4OTAtYmNkZS1mMTIzNDU2Nzg5MDEifQ

Opaque cursor returned as meta.next_cursor from the previous page

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success",
  • "message": "Rulesets retrieved successfully"
}

Get a ruleset by ID

Retrieves a single ruleset by its unique identifier, including all associated business rules.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a ruleset

Updates the metadata of a ruleset (name, description, attributes).

Only rulesets in draft status can be updated. Active or deprecated rulesets are immutable — create a new version instead.

This does not modify individual rules. Use the rule-level endpoints to add, update, or remove rules.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated human-readable name

description
string

Updated description

object or null

Updated metadata

Responses

Request samples

Content type
application/json
{
  • "name": "Motor Vehicle Rating Rules (Updated)",
  • "description": "Validation, pricing, and eligibility rules for comprehensive motor insurance",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Test a ruleset against input facts

Evaluates the entire ruleset against the provided input facts and returns the evaluation results.

This is a dry-run — no state is modified. The response includes a full explanation tree showing which rules fired, their inputs, intermediate results, and final decisions (platform principle explainability).

The ruleset must be active before this endpoint runs. Testing a draft ruleset returns 409 RULESET_NOT_ACTIVE; use /test-rule for isolated expression checks while authoring.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
required
object

Input facts for rule evaluation. Structure depends on the ruleset's entity_type and the rules defined within it.

Responses

Request samples

Content type
application/json
{
  • "facts": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Test a single rule within a ruleset

Evaluates a single rule expression against the provided input facts. Useful for iterative rule development and debugging before the rule is added to a ruleset.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
expression
required
string

CEL expression to test.

required
object

Input facts for rule evaluation

Responses

Request samples

Content type
application/json
{
  • "expression": "applicant.age >= 18",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Deploy a ruleset

Transitions a ruleset from draft to active status, making it available for evaluation in live policy, claim, and premium workflows.

This increments the ruleset version number. The previous active version (if any) is transitioned to deprecated and retained for as-was auditability.

This operation cannot be undone — to roll back, deploy the previous version's rules in a new ruleset.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
activated_by
required
string

Actor identifier recorded in the deployment audit trail.

Responses

Request samples

Content type
application/json
{
  • "activated_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Ruleset deployed successfully"
}

Add a rule to a ruleset

Adds a new business rule to a ruleset. The ruleset must be in draft status.

Rules are defined as CEL (Common Expression Language) expressions that must be deterministic and side-effect free.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string

Machine-readable rule code (must be unique within the ruleset)

name
required
string

Human-readable rule name

rule_type
required
string
Enum: "validation" "calculation" "condition" "action" "commission_rate" "commission_split" "group_discount" "discount_composition"

Classification of the rule's purpose

expression
required
string

CEL expression for rule evaluation. Both complex expressions (e.g., "cover.sum_insured <= 50000000") and bare literals (e.g., "25000") are valid CEL.

description
string or null

Human-readable explanation of the rule

priority
required
integer

Execution priority (lower executes first)

object or null

Optional rule metadata

Array of objects or null (RuleCondition)

Structured conditions evaluated before the expression

Array of objects or null (RuleAction)

Actions to execute when the rule evaluates to true

Responses

Request samples

Content type
application/json
{
  • "code": "max-vehicle-age",
  • "name": "Maximum Vehicle Age",
  • "rule_type": "validation",
  • "expression": "vehicle.year_of_manufacture >= 2011",
  • "description": "Vehicle must be no more than 15 years old for comprehensive cover in the test year",
  • "priority": 20,
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a rule within a ruleset

Updates an existing business rule within a ruleset. The ruleset must be in draft status.

Updatable fields: name, expression, description, priority, status, attributes, conditions, actions.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

ruleId
required
string <uuid>
Example: 0b601f31-c78a-5246-92a7-2ed20988ebfe

Rule UUID identifier within the ruleset

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated rule name

expression
string

Updated CEL expression

description
string or null

Updated description

priority
integer

Updated execution priority

status
string
Enum: "draft" "active" "deprecated"

Updated rule status

object or null

Updated metadata

Array of objects or null (RuleCondition)
Array of objects or null (RuleAction)

Responses

Request samples

Content type
application/json
{
  • "name": "Maximum Vehicle Age (Extended)",
  • "expression": "vehicle.year_of_manufacture >= 2006",
  • "description": "Vehicle must be no more than 20 years old for extended comprehensive cover",
  • "priority": 20,
  • "status": "draft",
  • "attributes": { },
  • "conditions": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Delete a rule from a ruleset

Removes a rule from a ruleset. The ruleset must be in draft status.

Rules in active or deprecated rulesets cannot be deleted — deprecate the rule instead to preserve the audit trail.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

ruleId
required
string <uuid>
Example: 0b601f31-c78a-5246-92a7-2ed20988ebfe

Rule UUID identifier within the ruleset

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Vendor

Vendor registry and risk management (governed contract). Tracks vendors, integrations, data access, and subprocessor approvals.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Register a new vendor

Creates a vendor record for a third-party service provider.

Vendors represent external organisations that process, store, or access tenant data. Each vendor is tracked for compliance purposes (POPIA, GDPR) including data classification, security review status, and subprocessor chains.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List vendors

Returns a paginated list of vendor records for the tenant.

Supports cursor-based pagination via page[size] and page[after] query parameters. Response uses a JSON:API-style collection envelope with data array and meta object.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of vendors to return (default 20, max 100)

page[after]
string

Opaque cursor for next page; obtained from previous response meta.next_cursor

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a vendor by ID

Returns the full vendor record including integrations and subprocessors. Response uses JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Vendor UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a vendor

Partially updates a vendor record. Only provided fields are modified. Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Vendor UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a subprocessor to a vendor

Registers a subprocessor under a vendor. Subprocessors are third parties that the vendor engages to process data on behalf of the tenant.

Tracking subprocessors is required for POPIA and GDPR compliance, ensuring the full data processing chain is documented and approved.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Parent vendor UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a subprocessor

Partially updates a subprocessor record under a vendor. Typically used to change approval status or update service scope.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Parent vendor UUID

subprocessor_id
required
string <uuid>
Example: d3216bd6-21dd-572a-8396-9e1444af9bfb

Subprocessor UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhook

Outbound webhook dispatch (governed contract). Register webhook endpoints and track delivery status. Uses JSON:API response format.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Register a webhook endpoint

Registers or updates a tenant-scoped outbound webhook endpoint.

This is an alpha transport-configuration surface governed by the Mailroom transport registry, not an ordinary product API operation. It records where outbound webhook deliveries may be sent and how the delivery should be authenticated. Event subscription catalogues and delivery routing rules are not yet published as a public self-service contract. Do not send event_types, event schemas, routing rules, ordering keys, or replay policy in this request; those semantics are governed separately before publication.

Secrets are supplied by reference only. Do not send raw secret material in the request body.

For auth_method=hmac_sha256, each outbound delivery includes:

  • X-Axiom-Delivery-Id: typed whd_ durable delivery id.
  • X-Correlation-ID: support trace id for the delivery workflow.
  • X-Webhook-Timestamp: Unix seconds in UTC.
  • X-Webhook-Signature: sha256=<hex> where the digest is HMAC-SHA256(secret, X-Webhook-Timestamp + "." + raw request body bytes).

Receivers should reject missing, malformed, stale, or mismatched signatures before processing the payload. A five-minute replay window is the alpha recommendation unless the issued integration runbook specifies a stricter tenant policy.

Outbound webhook delivery is at-least-once. Exactly-once delivery, global ordering, and per-endpoint ordering are not guaranteed in the alpha public contract. The same X-Axiom-Delivery-Id is reused across retry attempts for one delivery record, but it is not a stable canonical event id across endpoints, event streams, or schema revisions. Receivers must be idempotent and tolerate duplicate, delayed, and out-of-order deliveries.

Response format: Canonical success envelope.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
name
required
string [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]+$

Tenant-scoped endpoint name. Reusing the same name updates mutable endpoint settings.

url
required
string <uri>

HTTPS endpoint URL where webhook payloads will be delivered. Runtime validation rejects non-HTTPS URLs and known private, loopback, link-local, and non-routable targets.

description
string

Human-readable description of this endpoint's purpose.

auth_method
required
string
Default: "hmac_sha256"
Enum: "hmac_sha256" "bearer_token_ref" "none"

Authentication method for webhook deliveries.

  • hmac_sha256: HMAC signature over timestamp and raw body bytes.
  • bearer_token_ref: bearer token resolved from auth_secret_ref at dispatch time.
  • none: unsigned delivery; admitted only where tenant policy allows it.
auth_secret_ref
string

Opaque secret reference resolved by the Mailroom dispatcher. Required when auth_method is hmac_sha256 or bearer_token_ref. Raw secret material must not be sent in this field.

enabled
boolean
Default: true

Whether the endpoint is active

max_retries
required
integer [ 0 .. 10 ]

Number of retry attempts after the first delivery attempt.

backoff_seconds
required
Array of integers[ items [ 1 .. 3600 ] ]

Retry backoff values in seconds. The array length must equal max_retries; each value must be between 1 and 3600 seconds.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "primary-events",
  • "url": "https://receiver.example.com/axiom/webhooks",
  • "description": "Primary outbound event receiver",
  • "auth_method": "hmac_sha256",
  • "auth_secret_ref": "ref:webhooks/primary-events-signing-key",
  • "max_retries": 3,
  • "backoff_seconds": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Get webhook delivery status

Returns the current status of a specific outbound webhook delivery.

Delivery identifiers use the typed whd_ wire form. The response reports current lifecycle state, attempt count, retry budget, redacted error fields, correlation id, and linked intent id where available. Per-attempt response-history publication is not part of the alpha public contract.

The delivery id is stable across retry attempts for the same delivery record and is useful for receiver retry dedupe and support evidence. It is not a stable canonical event id. Webhook consumers must not assume exactly-once delivery or ordered delivery from this route.

Response format: Canonical success envelope.

Authorizations:
BearerAuth
path Parameters
delivery_id
required
string^whd_[A-Za-z0-9_-]+$
Example: whd_8a9b0c1d2e345678901bcdef0123456

Typed webhook delivery identifier.

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success"
}