API docs by Redocly

Axiom Platform API (0.2.39)

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, covers/products, 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, retained claim-family compatibility 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

Request correlation ID for tracing

Responses

Response samples

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

Get retained claim-family status breakdown

Published for route accountability in API 0.1.0. The route name and operationId are retained public compatibility identifiers over event/assertion status analytics. 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

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

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

Request correlation ID for tracing

Responses

Response samples

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

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, event, assertion, 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

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": "string",
  • "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 contract-response payments and adjustments.

Authorizations:
BearerAuth
query Parameters
policy_id
required
string
Example: policy_id=ref_20260408_0001

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
Example: policy_id=ref_20260408_0001

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": { }
}

Retained benefit claims-ratio route under schema reconciliation

This route is intentionally unavailable in alpha. It remains present for route accountability as a retained public compatibility identifier, but consumers must use the benefit balance and available-benefit routes until the event/assertion and cover/entitlement model authority exists for this ratio.

Authorizations:
BearerAuth
path Parameters
id
required
string

Resource identifier.

Responses

Response samples

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

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

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

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 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

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

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.

Record retained claim-family authorisation

Record an governed contract authorisation sub-event against the retained claim-family compatibility surface. Axiom canon is events/assertions; the authorisation row is append-only and carries the authorising actor, authorised scope, budget, governing-version binding, optional compliance state, decision date, and explanation-node reference.

Payment operations 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 retained claim-family compatibility 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

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

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

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

Explanation-node reference for the authorisation decision.

finding_reference
string or null

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": "usr_20260408_0001",
  • "authorised_scope": {
    },
  • "budget_minor": 250000,
  • "budget_currency_code": "zar",
  • "governing_version_kind": "catalogue",
  • "governing_version_row_id": "governance_version_20260408_0001",
  • "decision_date": "2026-07-06T10:00:00Z",
  • "explanation_node_id": "explanation_node_20260408_0001"
}

Response samples

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

Close retained claim-family resource

Close a retained claim-family compatibility resource through the runtime service. The handler enforces tenant context, typed compatibility IDs, actor attribution, and terminal-state transition checks before recording the closure.

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

Unique retained claim-family compatibility 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 retained compatibility resource.

closed_by
string

Identifier of the user or system closing the retained compatibility resource.

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
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Generate retained claim-family PDF report

Generate a PDF document summarising the retained claim-family compatibility resource, including event details, assessment results, payment information, and lifecycle history.

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

The generated PDF includes:

  • Retained compatibility header (claim number, policy number, status)
  • Event details and description
  • Retained line items with amounts
  • Assessment summary and notes
  • Payment details (if applicable)
  • Lifecycle timeline

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

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

Unique retained claim-family compatibility identifier.

query Parameters
party_id
string <typed-prefix-id>

Optional party access check for the generated claim report. When present, must be the canonical typed-prefix party id (pty_...) for the retained compatibility resource's primary party.

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": [
    ]
}

Get retained claim-family audit trail

Returns the tenant-scoped audit trail for the retained claim-family compatibility resource after verifying that it exists for the operating tenant.

Authorizations:
BearerAuth
path Parameters
id
required
string

Resource 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.

Responses

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
Example: cmp_eval_20260408_0001

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.2.0",
  • "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.2.0",
  • "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).

This operation reports workqueue execution status only. It does not expose workflow_execution_id, does not promise workflow execution tracking, and must not be treated as a public workflow execution registry.

Authorizations:
BearerAuth
path Parameters
job_id
required
string
Example: job_20260408_0001

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

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

Contract authority for GET /v1/events (listEvents) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Event

Contract authority for GET /v1/events/{id} (getEvent) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Upload Event Documents

Contract authority for POST /v1/events/{event_id}/documents (uploadEventDocuments) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
event_id
required
string

Path parameter event_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.

Responses

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

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": "string",
  • "affected": {
    },
  • "effective_times": {
    },
  • "inputs": { }
}

Response samples

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

Retained Claim Compatibility Submit

Compatibility contract for retained POST /v1/claims (submitClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility List

Compatibility contract for retained GET /v1/claims (listClaims) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Get

Compatibility contract for retained GET /v1/claims/{id} (getClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Retained Claim Compatibility Assess

Compatibility contract for retained POST /v1/claims/{id}/assess (assessClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; the route assesses the contract-facing assertion for the retained claim-family surface. Claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Pay

Compatibility contract for retained POST /v1/claims/{id}/pay (payClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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
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

authorisation_id
string or null

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
{
  • "paid_amount": {
    },
  • "payment_method": "bank_transfer",
  • "payment_notes": "Final settlement — retained assertion fully resolved",
  • "authorisation_id": "clm_01abcdefghjkmnpqrstvwxyz01",
  • "metadata": {
    }
}

Response samples

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

Create Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves (createReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Reserve List

Compatibility contract for retained GET /v1/claims/{id}/reserves (listClaimReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Get Reserve

Compatibility contract for retained GET /v1/claims/{id}/reserves/{reserveId} (getReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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

Update Reserve

Compatibility contract for retained PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Release Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Cancel Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Reestablish Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

List Policy Reserves

Compatibility contract for retained GET /v1/claims/reserves (listPolicyReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Or Advance Investigation

Compatibility contract for retained POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Recovery

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries (createRecovery) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

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.

Responses

Create Correction

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

recoveryId
required
string

Path parameter recoveryId.

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.

Responses

Retained Claim Compatibility Get Settlement Statement

Compatibility contract for retained GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

decisionId
required
string

Path parameter decisionId.

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

List Assertions

Contract authority for GET /v1/assertions (listAssertions) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Assertion

Contract authority for GET /v1/assertions/{id} (getAssertion) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Receive Inbox Message

Contract authority for POST /v1/inbox/messages (receiveInboxMessage) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Webhook Delivery Status

Contract authority for GET /v1/mailroom/outbox/webhook-deliveries/{delivery_id} (getWebhookDeliveryStatus) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
delivery_id
required
string

Path parameter delivery_id.

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

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

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

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": "subject_ref_20260408_0001",
  • "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
Example: evd_20260408_0001

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": "assertion",
  • "subject_id": "subject_ref_20260408_0001",
  • "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
Example: evd_20260408_0001

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 [ 1 .. 100 ] items

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

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
Example: evd_20260408_0001

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.2.39"
}

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": { }
}

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

Receives an event into the Axiom ingress pipeline for asynchronous validation and processing.

This is an admitted alpha transport surface for asynchronous external inputs. It persists a durable inbox record and a tenant-scoped status record before returning 202 Accepted. 202 Accepted means durable receipt only. It does not mean the submitted event is valid, accepted into the insurance domain, processed, or linked downstream.

Callers must use the returned status_url or subscribe to a governed notification channel when available. Polling the status endpoint is the authoritative way to discover later validation and processing outcomes.

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, current receipt status, and status_url.

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": {
    }
}

Get ingress event status

Returns the tenant-scoped status trail for an asynchronous event submission.

Use this endpoint after POST /v1/ingress/events returns 202 Accepted. The status endpoint is authoritative: webhook or email notification delivery can fail without hiding the validation result from the caller.

Status separates receipt, validation, domain acceptance, processing, and completion:

  • received means Axiom has durably received the submission.
  • validation_failed means the submission failed asynchronous validation.
  • accepted means validation has passed far enough for domain processing.
  • processing_failed means domain processing failed after acceptance.
  • completed means processing completed and any resulting domain reference is visible in the response where available.

No domain event or assertion exists until the ingress record reaches an accepted/processing/completed state.

Authorizations:
BearerAuth
path Parameters
ingress_id
required
string

Assigned ingress record identifier returned by POST /v1/ingress/events.

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": {
    }
}

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

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
Example: ref_20260408_0001

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

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 retained claim-family compatibility 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

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 (for example a retained claim-family compatibility id, policy id, premium id, 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, for example a retained claim-family compatibility id, policy id, premium id, or 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

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
Example: ref_20260408_0001

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

Request correlation ID for tracing

Responses

Response samples

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

Lifecycle Authoring

Insurance lifecycle authoring — tenant-owned lifecycle definitions, compliance packs, validation, publication, and bindings. This is governed insurance product grammar and does not expose generic workflow/BPMN authoring, public PipelineTemplate authoring, or raw public rule evaluation.

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 Lifecycle Definition Draft

Create a tenant-owned draft insurance lifecycle definition for an admitted product or business object. The server derives tenant authority from X-Tenant-Context and rejects generic workflow, BPMN, public PipelineTemplate, and raw public rule-evaluation authoring.

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
lifecycle_key
required
string^[a-z][a-z0-9_:-]{2,127}$

Server-scoped lifecycle key. It is not a raw workflow or PipelineTemplate identifier.

product_id
required
string^[a-z][a-z0-9_:-]{2,127}$

Product or cover catalogue identifier governed by the operating tenant.

business_object_kind
string
Enum: "policy" "replacement" "endorsement" "claim" "assertion" "premium" "payment"
lifecycle_purpose
required
string
Enum: "replacement" "endorsement" "claim" "assertion" "premium_collection" "payment_schedule" "policy_issue" "policy_cancellation"
jurisdiction
string [ 2 .. 16 ] characters ^[a-z][a-z0-9_:-]{1,15}$
authoring_kind
string
Value: "insurance_lifecycle"

Closed authoring kind. Generic workflow, BPMN, raw PipelineTemplate, and raw rule evaluation are rejected.

initial_state
required
string
terminal_states
Array of strings non-empty
required
Array of objects (LifecycleState) >= 2 items
required
Array of objects (LifecycleTransition) non-empty
compliance_pack_keys
Array of strings
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleExplanationObligation) non-empty
object

Responses

Request samples

Content type
application/json
{
  • "lifecycle_key": "string",
  • "product_id": "string",
  • "business_object_kind": "policy",
  • "lifecycle_purpose": "replacement",
  • "jurisdiction": "za",
  • "authoring_kind": "insurance_lifecycle",
  • "initial_state": "string",
  • "terminal_states": [
    ],
  • "states": [
    ],
  • "transitions": [
    ],
  • "compliance_pack_keys": [
    ],
  • "evidence_obligations": [
    ],
  • "audit_obligations": [
    ],
  • "retention_obligations": [
    ],
  • "explanation_obligations": [
    ],
  • "metadata": {
    }
}

Response samples

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

Validate Lifecycle Definition Draft

Validate an insurance lifecycle definition draft against Axiom lifecycle grammar, custody, transition, evidence, retention, and explanation rules before publication. Validation is deterministic and fails closed for generic workflow/BPMN, public PipelineTemplate, raw public rule evaluation, and caller-supplied tenant authority.

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
required
object (LifecycleDefinitionDraftRequest)

Responses

Request samples

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

Response samples

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

Publish Lifecycle Definition

Publish a validated lifecycle definition version. Published versions are immutable, effective-time bound, and become eligible for server-side lifecycle binding resolution only after validation and publication evidence are recorded.

Authorizations:
BearerAuth
path Parameters
definition_id
required
string

Path parameter definition_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
expected_version
required
integer >= 1
effective_from
required
string <date-time>
validation_receipt_id
required
string
canonical_request_hash
required
string^sha256:[a-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "expected_version": 1,
  • "effective_from": "2019-08-24T14:15:22Z",
  • "validation_receipt_id": "string",
  • "canonical_request_hash": "string"
}

Response samples

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

Create Compliance Pack Draft

Create a tenant-owned compliance-pack draft that can be pinned by lifecycle definitions and bindings. The pack records jurisdiction, legal references, obligations, evidence, disclosures, time gates, retention, and activation posture without becoming code-hidden compliance behavior.

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
pack_key
required
string^[a-z][a-z0-9_:-]{2,127}$
jurisdiction
required
string
required
Array of objects (LifecycleObligation) non-empty
legal_references
required
Array of strings non-empty
evidence_requirements
required
Array of strings non-empty
required
Array of objects (LifecycleObligation) non-empty
Array of objects

Responses

Request samples

Content type
application/json
{
  • "pack_key": "string",
  • "jurisdiction": "string",
  • "obligations": [
    ],
  • "legal_references": [
    ],
  • "evidence_requirements": [
    ],
  • "retention_obligations": [
    ],
  • "time_gates": [
    ]
}

Response samples

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

Create Lifecycle Binding

Create an effective-time lifecycle binding from tenant/product/business-object scope to published lifecycle definition and compliance-pack versions. The server resolves tenant authority and callers cannot supply raw PipelineTemplate identifiers, raw ruleset selectors, or tenant override facts.

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
product_id
required
string^[a-z][a-z0-9_:-]{2,127}$
business_object_kind
string
Enum: "policy" "replacement" "endorsement" "claim" "assertion" "premium" "payment"
lifecycle_purpose
required
string
jurisdiction
required
string^[a-z][a-z0-9_:-]{1,15}$
definition_key
required
string^[a-z][a-z0-9_:-]{2,127}$
definition_version
required
integer >= 1
definition_content_hash
required
string^sha256:[a-f0-9]{64}$
Array of objects (CompliancePackPin)
effective_from
required
string <date-time>
effective_until
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "product_id": "string",
  • "business_object_kind": "policy",
  • "lifecycle_purpose": "string",
  • "jurisdiction": "string",
  • "definition_key": "string",
  • "definition_version": 1,
  • "definition_content_hash": "string",
  • "compliance_pack_pins": [
    ],
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_until": "2019-08-24T14:15:22Z"
}

Response samples

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

Party

Party management — individuals, organisations, brokers, agents, and providers. Parties are the actors in the policy lifecycle (policyholder roles, asserting parties, beneficiary roles, capacity-bearing parties).

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
group_id
string
valid_from
string <date-time>

Defaults to now() server-side when omitted

Responses

Request samples

Content type
application/json
{
  • "party_id": "string",
  • "group_id": "string",
  • "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
as_of
string <date-time>

Defaults to now() server-side

Responses

Request samples

Content type
application/json
{
  • "party_id": "string",
  • "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

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.

Idempotency-Key
required
string [ 1 .. 256 ] characters
Example: idem-payment-20260821-001

Client-supplied idempotency key for replay-safe mutation requests.

The server scopes the key to the tenant, HTTP method, and matched path. A replay with the same key and same payload returns the original response. A replay with the same key and a different payload returns 409 CONFLICT. A concurrent replay while the first request is still in flight returns 409 CONFLICT with Retry-After.

X-Correlation-ID
string

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

Reference to the associated resource (premium, retained claim-family compatibility resource, etc.)

reference_type
string or null

Type of the referenced resource

party_id
string or null

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": "ref_20260408_0001",
  • "reference_type": "premium",
  • "party_id": "pty_01abcdefghjkmnpqrstvwxyz01",
  • "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
Example: pay_20260403_0001

Typed payment 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": { }
}

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
Example: pay_20260403_0001

Typed payment 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

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

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": "string",
  • "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
Example: pay_20260403_0001

Typed payment 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.

Idempotency-Key
required
string [ 1 .. 256 ] characters
Example: idem-payment-20260821-001

Client-supplied idempotency key for replay-safe mutation requests.

The server scopes the key to the tenant, HTTP method, and matched path. A replay with the same key and same payload returns the original response. A replay with the same key and a different payload returns 409 CONFLICT. A concurrent replay while the first request is still in flight returns 409 CONFLICT with Retry-After.

X-Correlation-ID
string

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
Example: pay_20260403_0001

Typed payment 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.

Idempotency-Key
required
string [ 1 .. 256 ] characters
Example: idem-payment-20260821-001

Client-supplied idempotency key for replay-safe mutation requests.

The server scopes the key to the tenant, HTTP method, and matched path. A replay with the same key and same payload returns the original response. A replay with the same key and a different payload returns 409 CONFLICT. A concurrent replay while the first request is still in flight returns 409 CONFLICT with Retry-After.

X-Correlation-ID
string

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

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 lifecycle 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

Request correlation ID for tracing

Request Body schema: application/json
required
policy_id
required
string

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": "pol_01abcdefghjkmnpqrstvwxyz01",
  • "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 lifecycle is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: pay_20260403_0001

Typed payment schedule 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
Example
{
  • "errors": [
    ]
}

Pause a payment schedule

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the payment-schedule lifecycle state machine is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: pay_20260403_0001

Typed payment schedule 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
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 lifecycle state machine is implemented.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: pay_20260403_0001

Typed payment schedule 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
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

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

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

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

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

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

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": "string",
  • "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

Identifier of the product to issue the policy under

required
string or string

Date from which the policy provides coverage. YYYY-MM-DD and RFC3339 date-time are accepted; runtime normalizes the value before persistence.

required
string or string

Date on which the policy coverage ends. YYYY-MM-DD and RFC3339 date-time are accepted; runtime normalizes the value before persistence.

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

Optional caller-supplied audit label. Authoritative actor attribution is derived from the authenticated actor context when omitted.

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": "prd_01abcdefghjkmnpqrstvwxyz01",
  • "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 covers/products 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

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: creates a new immutable policy version through the VersionService, including retroactive guard enforcement, rule snapshot capture, atomic close/open validity transition, explanation provenance, outbox emission, and post-mutation audit.

Authorizations:
BearerAuth
path Parameters
id
required
string

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

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

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

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

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

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

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 Lifecycle Definition Draft

Create a tenant-owned draft insurance lifecycle definition for an admitted product or business object. The server derives tenant authority from X-Tenant-Context and rejects generic workflow, BPMN, public PipelineTemplate, and raw public rule-evaluation authoring.

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
lifecycle_key
required
string^[a-z][a-z0-9_:-]{2,127}$

Server-scoped lifecycle key. It is not a raw workflow or PipelineTemplate identifier.

product_id
required
string^[a-z][a-z0-9_:-]{2,127}$

Product or cover catalogue identifier governed by the operating tenant.

business_object_kind
string
Enum: "policy" "replacement" "endorsement" "claim" "assertion" "premium" "payment"
lifecycle_purpose
required
string
Enum: "replacement" "endorsement" "claim" "assertion" "premium_collection" "payment_schedule" "policy_issue" "policy_cancellation"
jurisdiction
string [ 2 .. 16 ] characters ^[a-z][a-z0-9_:-]{1,15}$
authoring_kind
string
Value: "insurance_lifecycle"

Closed authoring kind. Generic workflow, BPMN, raw PipelineTemplate, and raw rule evaluation are rejected.

initial_state
required
string
terminal_states
Array of strings non-empty
required
Array of objects (LifecycleState) >= 2 items
required
Array of objects (LifecycleTransition) non-empty
compliance_pack_keys
Array of strings
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleObligation) non-empty
required
Array of objects (LifecycleExplanationObligation) non-empty
object

Responses

Request samples

Content type
application/json
{
  • "lifecycle_key": "string",
  • "product_id": "string",
  • "business_object_kind": "policy",
  • "lifecycle_purpose": "replacement",
  • "jurisdiction": "za",
  • "authoring_kind": "insurance_lifecycle",
  • "initial_state": "string",
  • "terminal_states": [
    ],
  • "states": [
    ],
  • "transitions": [
    ],
  • "compliance_pack_keys": [
    ],
  • "evidence_obligations": [
    ],
  • "audit_obligations": [
    ],
  • "retention_obligations": [
    ],
  • "explanation_obligations": [
    ],
  • "metadata": {
    }
}

Response samples

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

Validate Lifecycle Definition Draft

Validate an insurance lifecycle definition draft against Axiom lifecycle grammar, custody, transition, evidence, retention, and explanation rules before publication. Validation is deterministic and fails closed for generic workflow/BPMN, public PipelineTemplate, raw public rule evaluation, and caller-supplied tenant authority.

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
required
object (LifecycleDefinitionDraftRequest)

Responses

Request samples

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

Response samples

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

Publish Lifecycle Definition

Publish a validated lifecycle definition version. Published versions are immutable, effective-time bound, and become eligible for server-side lifecycle binding resolution only after validation and publication evidence are recorded.

Authorizations:
BearerAuth
path Parameters
definition_id
required
string

Path parameter definition_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
expected_version
required
integer >= 1
effective_from
required
string <date-time>
validation_receipt_id
required
string
canonical_request_hash
required
string^sha256:[a-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "expected_version": 1,
  • "effective_from": "2019-08-24T14:15:22Z",
  • "validation_receipt_id": "string",
  • "canonical_request_hash": "string"
}

Response samples

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

Create Compliance Pack Draft

Create a tenant-owned compliance-pack draft that can be pinned by lifecycle definitions and bindings. The pack records jurisdiction, legal references, obligations, evidence, disclosures, time gates, retention, and activation posture without becoming code-hidden compliance behavior.

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
pack_key
required
string^[a-z][a-z0-9_:-]{2,127}$
jurisdiction
required
string
required
Array of objects (LifecycleObligation) non-empty
legal_references
required
Array of strings non-empty
evidence_requirements
required
Array of strings non-empty
required
Array of objects (LifecycleObligation) non-empty
Array of objects

Responses

Request samples

Content type
application/json
{
  • "pack_key": "string",
  • "jurisdiction": "string",
  • "obligations": [
    ],
  • "legal_references": [
    ],
  • "evidence_requirements": [
    ],
  • "retention_obligations": [
    ],
  • "time_gates": [
    ]
}

Response samples

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

Create Lifecycle Binding

Create an effective-time lifecycle binding from tenant/product/business-object scope to published lifecycle definition and compliance-pack versions. The server resolves tenant authority and callers cannot supply raw PipelineTemplate identifiers, raw ruleset selectors, or tenant override facts.

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
product_id
required
string^[a-z][a-z0-9_:-]{2,127}$
business_object_kind
string
Enum: "policy" "replacement" "endorsement" "claim" "assertion" "premium" "payment"
lifecycle_purpose
required
string
jurisdiction
required
string^[a-z][a-z0-9_:-]{1,15}$
definition_key
required
string^[a-z][a-z0-9_:-]{2,127}$
definition_version
required
integer >= 1
definition_content_hash
required
string^sha256:[a-f0-9]{64}$
Array of objects (CompliancePackPin)
effective_from
required
string <date-time>
effective_until
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "product_id": "string",
  • "business_object_kind": "policy",
  • "lifecycle_purpose": "string",
  • "jurisdiction": "string",
  • "definition_key": "string",
  • "definition_version": 1,
  • "definition_content_hash": "string",
  • "compliance_pack_pins": [
    ],
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_until": "2019-08-24T14:15:22Z"
}

Response samples

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

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

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": "string",
  • "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

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

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 malformed typed identifier 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 malformed typed identifier returns 400.

Responses

Request samples

Content type
application/json
Example
{
  • "policy_id": "pol_6wcq9sjx7b8q8vwbhdzbwdzzbd",
  • "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

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"
}

Calculate a premium quotation

Calculate a premium quotation for a given product and rating profile. This is a read-only operation that does not create any records -- it returns the calculated premium breakdown including base premium, adjustments, commissions, and totals.

The calculation uses the product's configured pricing rules and evaluates them against the provided rating factors. Each adjustment is itemised with the rule name and human-readable explanation for full transparency.

On the CEL pricing path (triggered by effective_date in rating_inputs), commission is derived from versioned CEL rules classified as entity_type=pricing and rule_type=commission_rate within the same ruleset binding. When no commission rule exists for the resolved product and effective date, commission is zero and the commissions list is empty; legacy product JSON is not consulted. Commission amounts are exact int64 minor units; float outputs are rejected.

This endpoint supports quote journeys where the premium is calculated before a policy is issued.

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 being priced. Required for CEL context assembly.

product_id
required
string

Reference to the product to calculate premium for

required
object

Rating inputs for premium calculation. When effective_date is present (RFC3339 format), the CEL-based pricing path is used with as-was binding resolution. Without effective_date, the legacy pricing path applies.

Responses

Request samples

Content type
application/json
Example
{
  • "policy_id": "pol_6wcq9sjx7b8q8vwbhdzbwdzzbd",
  • "product_id": "prd_01abcdefghjkmnpqrstvwxyz01",
  • "rating_inputs": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "status": "success",
  • "message": "Premium calculated successfully"
}

Post a balanced premium cancellation refund

Computes the cancellation return-premium for the supplied policy/event using the as-was product ruleset binding (governed contract). Non-zero refunds post a balanced premium_refund ledger transaction (governed contract) — one debit against premium-income and one credit against premium-refund-payable. Zero-refund decisions persist an explanation tree and return an empty ledger entry list without fabricating ledger rows. The refund amount is calculated by the configured method on the binding: pro_rata, short_rate, or minimum_earned. All amounts are exact int64 minor units; basis points are int64 (governed contract).

The same call durably persists an AC-7 explanation tree (governed contract). For non-zero refunds the tree is persisted in the same transaction as the ledger entries; the persisted tree's ID is stamped on both ledger legs as explanation_tree_id.

Idempotency is keyed strictly on the client-supplied Idempotency-Key header (governed contract). Replays return 200 OK with is_replay=true and the original transaction's ledger entry IDs; first-posts return 201 Created. An empty Idempotency-Key returns 422 IDEMPOTENCY_KEY_REQUIRED.

Cancellation return premium (pro-rata, short-rate, minimum-earned). All required inputs and configuration must be present and well-formed; missing or malformed cancellation_refund.* keys surface as typed 422 errors with stable codes.

Authorizations:
BearerAuth
path Parameters
id
required
string

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

Idempotency-Key
required
string non-empty

Client-supplied idempotency key (governed contract). Required. The server derives the per-leg ledger row keys as {Idempotency-Key}:debit and {Idempotency-Key}:credit. Replays of the same key return the original transaction with is_replay=true and write no new rows.

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": {
    }
}

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

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": { }
}

Collect a premium payment

Record a collected premium payment as a balanced ledger transaction with one debit entry and one or more per-allocation credit entries. The request is idempotent by business event: replay returns the original transaction with is_replay=true and no duplicate ledger entries.

Authorizations:
BearerAuth
path Parameters
id
required
string

Premium identifier. Accepts the canonical prm_... typed-prefix form or a UUID.

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": {
    },
  • "status": "success"
}

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}$

Lowercase ISO-4217 currency code. Uppercase input is accepted and normalized to lowercase canonical form by the runtime.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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" "suspended" "discontinued"

Updated product lifecycle status. Status-only changes use the status-only persistence path and do not rewrite the cover graph.

base_premium
integer <int64>

Base premium amount in the smallest currency unit.

object or null

Updated extensible attributes.

updated_by
string
Deprecated

Retired compatibility field. Product update attribution is derived from the authenticated actor context.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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

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": "string",
  • "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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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": { }
}

Evaluate a governed product decision intent

Contract-admitted operation for external process tooling to ask Axiom a named governed product decision question at a process decision point. Axiom owns tenant context, product binding resolution, ruleset/pipeline selection, audit evidence, and explanation evidence.

This Slice 2 contract admits the runtime binding skeleton. A runtime call is parsed, tenant-bound, actor-bound, checked against the contract-owned allowlists, and delegated to the internal Product Decision Evaluation service. Until ruleset or pipeline execution, audit persistence, and explanation persistence are wired, the service must fail closed with a typed technical error, never with a business outcome.

Callers must not supply raw ruleset_id, raw pipeline template identifiers, tenant authority fields, retention policy, explanation audience overrides, or transport-failure-to-business-outcome mappings. BPMN and workflow engines route only on the stable decision_code returned by Axiom after a successful evaluation.

Authorizations:
BearerAuth
path Parameters
id
required
string^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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 [ 8 .. 128 ] characters ^[A-Za-z0-9._:-]+$

Idempotency key scoped by operating tenant.

Request Body schema: application/json
required
decision_intent
required
string (ProductDecisionIntent) ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$

Decision intent name from the contract-owned decision-intent registry. Slice 1 admits the naming and validation shape; runtime registry lookup is owned by the implementation slice.

product_stage
required
string (ProductDecisionStage) ^[a-z][a-z0-9_]*$

Product-stage name from the contract-owned product-stage registry. A stage names process decision context; it does not select a ruleset or workflow model.

effective_at
required
string <date-time>

Timestamp used for as-was product binding resolution.

requested_outputs
required
Array of strings (ProductDecisionRequestedOutput) non-empty unique
Items Enum: "decision_code" "reason_codes" "routeable_outputs" "required_document_codes" "premium_amount" "referral_reason" "settlement_amount"
required
object

Controlled input facts or references needed by the named decision intent. Facts are data only and never grant tenant, ruleset, pipeline, retention, or explanation authority. Runtime evaluation must reject nested authority-shaped facts such as raw ruleset, pipeline, tenant, retention, explanation-audience, transport-status, or infrastructure-status selectors.

canonical_request_hash
required
string^sha256:[a-f0-9]{64}$

SHA-256 hash of the canonical product decision evaluation request payload. The canonical payload contains exactly decision_intent, product_stage, effective_at normalized to UTC RFC3339/RFC3339Nano, requested_outputs in caller-supplied order, and facts. It excludes canonical_request_hash, the path product id, tenant context, actor context, correlation headers, and idempotency headers. The canonical payload bytes are compact UTF-8 JSON with lexicographically sorted object member names at every object depth and no insignificant whitespace. effective_at is rendered in UTC RFC3339Nano form with a trailing Z. JSON number values are encoded as JSON numbers, not strings. String values use JSON string escaping without HTML escaping.

Responses

Request samples

Content type
application/json
{
  • "decision_intent": "quote.premium_rating",
  • "product_stage": "quotation",
  • "effective_at": "2026-09-06T10:00:00Z",
  • "requested_outputs": [
    ],
  • "facts": {
    },
  • "canonical_request_hash": "sha256:0c4f36305a512094cb6ec2e150823254a2db606243293c210a8def41ed0be464"
}

Response samples

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

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^prd_[A-Za-z0-9]+$

Typed product identifier rendered by the API. The storage UUID remains internal.

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

Published for route accountability in API 0.1.0. The runtime currently returns 501 until the tenant-owned report-runner substrate is implemented.

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

When implemented, successful responses will return report file content rather than a JSON envelope. API 0.1.0 does not yet publish that runtime promise.

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

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, retained claim-family assessment, document completeness, or discount composition. Rules are data. — explicit, versioned, deterministic, and auditable.

Optionally specify a base_ruleset UUID to copy rules from an existing ruleset as a starting point. Copied rules preserve their business codes and receive new technical IDs.

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

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: "annual_cap" "cancellation_and_refunds" "claims_assessment" "commission" "coverage" "discount" "document_completeness" "eligibility" "payments" "premium_collection" "premium_rating" "procedure_eligibility" "proration_adjustments" "rating" "regulatory" "shortfall_calculation" "waiting_periods"

Canonical ruleset_type / pipeline stage this ruleset governs. The service validates this value against ProductRulesetBinding's canonical allowlist and rejects retired lane words such as claims, pricing, and underwriting.

description
required
string

Detailed description of the ruleset purpose

object or null

Optional metadata (jurisdiction, product line, etc.)

base_ruleset
string or null

Existing ruleset UUID to use as a creation-time template. Codes are not accepted for this field. The successor draft receives the next numeric version, lineage metadata in attributes, and copied rules with their business codes preserved. This is a bounded compatibility copy path only; governed evaluation composition uses CompositionResolver / PipelineExecutor and live ruleset bindings, not BaseRuleset snapshot inheritance.

Responses

Request samples

Content type
application/json
{
  • "code": "health-gap-ng-v1",
  • "name": "Nigeria Health Gap Cover",
  • "entity_type": "premium_rating",
  • "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

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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": { }
}

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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

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 lifecycles, retained claim-family compatibility lifecycles, and premium calculation pipelines.

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset 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

Request Body schema: application/json
required
code
required
string <= 50 characters ^[A-Za-z0-9_.:-]+$

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. JSON request facts may bind numeric values as CEL double values; use explicit int(), uint(), or double() conversions when an operator requires a specific numeric type.

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)
Deprecated

Legacy compatibility metadata only. Conditions are not executable rule authority in the governed ruleset runtime; the CEL expression field is the sole executable rule body.

Array of objects or null (RuleAction)
Deprecated

Legacy compatibility metadata only. Actions are preserved for historical rulepack round-trip evidence but are not executed by the ruleset runtime.

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset identifier

ruleId
required
string
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed rule 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

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
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed ruleset identifier

ruleId
required
string
Example: rst_01abcdefghjkmnpqrstvwxyz01

Typed rule 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

Request correlation ID for tracing

Responses

Response samples

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

SupportRequests

Tenant-facing support request intake and status over the canonical collaboration_request substrate. Internal triage, support-session approval, Council escalation, product commitment, and SDLC conversion operations are excluded from the public Support 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.

Submit a support request

Submit a support, incident, bug, enhancement, feature, documentation, integration, or commercial request into the canonical collaboration_request support lifecycle. Email and assisted support channels are adapter references only; this operation creates the same canonical record type. Public callers cannot approve support access, create internal work, make product commitments, or force internal lifecycle transitions.

Authorizations:
BearerAuth
header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Idempotency-Key
required
string non-empty

Required for support request mutations.

Request Body schema: application/json
required
request_class
required
string
Enum: "support_question" "incident" "bug_report" "integration_help" "enhancement_request" "feature_request" "documentation_request" "commercial_request"
summary
required
string non-empty
details
string
requester_reference
string
stated_severity
string
affected_environment
string
affected_surface
string
affected_canonical_noun
string
Enum: "parties_roles" "covers_products" "policies_versions" "premiums_payments" "events_assertions"
affected_substrate
string
correlation_ids
Array of strings
external_references
Array of strings

Inert references only; they are not fetched or promoted implicitly.

Array of objects (SupportAttachmentReference)
object (SupportAgentContext)
idempotency_key
string

Body mirror for clients that cannot set Idempotency-Key; header remains preferred.

Responses

Request samples

Content type
application/json
{
  • "request_class": "support_question",
  • "summary": "string",
  • "details": "string",
  • "requester_reference": "string",
  • "stated_severity": "string",
  • "affected_environment": "string",
  • "affected_surface": "string",
  • "affected_canonical_noun": "parties_roles",
  • "affected_substrate": "string",
  • "correlation_ids": [
    ],
  • "external_references": [
    ],
  • "attachment_refs": [
    ],
  • "agent_context": {
    },
  • "idempotency_key": "string"
}

Response samples

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

List visible support requests

List support requests visible to the authenticated actor in the current tenant/account scope. The response is tenant-isolated and exposes only redacted tenant-facing state and affordances.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
offset
integer >= 0
Default: 0
header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Responses

Response samples

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

Read a visible support request

Read one support request visible to the authenticated actor in the current tenant/account scope. Internal work links, support-session internals, Council material, and private triage notes are not tenant-facing authority.

Authorizations:
BearerAuth
path Parameters
request_id
required
string^crq_[0-9a-f-]{36}$

Canonical collaboration_request identifier.

header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Responses

Response samples

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

Add a support request message

Add a tenant-visible follow-up message to a support request thread. This operation appends communication content only; it cannot force internal state transitions such as accepted, converted_to_sdlc_intent, closed, or reopened.

Authorizations:
BearerAuth
path Parameters
request_id
required
string^crq_[0-9a-f-]{36}$

Canonical collaboration_request identifier.

header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Idempotency-Key
required
string non-empty

Required for support request mutations.

Request Body schema: application/json
required
body
required
string non-empty
adapter_ref
string
correlation_id
string

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "adapter_ref": "string",
  • "correlation_id": "string"
}

Response samples

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

Attach support evidence by custody reference

Attach or reference evidence that has already entered governed object custody. Raw URLs and adapter attachments are not evidence authority for this operation.

Authorizations:
BearerAuth
path Parameters
request_id
required
string^crq_[0-9a-f-]{36}$

Canonical collaboration_request identifier.

header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Idempotency-Key
required
string non-empty

Required for support request mutations.

Request Body schema: application/json
required
reference_class
required
string
Enum: "archive_object" "redacted_derivative" "communication_message" "support_session_disclosure" "audit_event" "gitlab_work_item" "council_record" "ci_release_evidence"
custody_ref
required
string
sha256
required
string^sha256:[0-9a-f]{16,64}$
classification
required
string
admission_status
required
string
redaction_status
required
string
retention_ref
required
string
legal_hold_ref
string
derived_from
string

Responses

Request samples

Content type
application/json
{
  • "reference_class": "archive_object",
  • "custody_ref": "string",
  • "sha256": "string",
  • "classification": "string",
  • "admission_status": "string",
  • "redaction_status": "string",
  • "retention_ref": "string",
  • "legal_hold_ref": "string",
  • "derived_from": "string"
}

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
Example: vnd_01abcdefghjkmnpqrstvwxyz01

Typed vendor 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. Security-review status is not accepted on this endpoint; use the authorized security-review decision endpoint. Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

Typed vendor 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": {
    }
}

Record an authorized vendor security-review decision

Records a security-review decision for a vendor through an explicitly authorized attestation workflow. Ordinary vendor updates cannot change security_review_status.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

Typed vendor 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
Example: vnd_01abcdefghjkmnpqrstvwxyz01

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. Approval status is not accepted on this endpoint; use the authorized subprocessor approval decision endpoint.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

Parent vendor UUID

subprocessor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

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": {
    }
}

Record an authorized subprocessor approval decision

Records a subprocessor approval decision through an explicitly authorized attestation workflow. Ordinary subprocessor create and update requests cannot set approval status, approver, or approval timestamp.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

Parent vendor UUID

subprocessor_id
required
string
Example: vnd_01abcdefghjkmnpqrstvwxyz01

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": { }
}

SupportSessions

List tenant support-session disclosures

List the bounded support-session disclosure history for the authenticated operating tenant. This route requires normal tenant context and never takes the tenant id from caller-supplied path or query input.

Authorizations:
BearerAuth
header Parameters
X-Correlation-ID
string

Correlation id for request tracing.

Responses

Response samples

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

assertions

List Events

Contract authority for GET /v1/events (listEvents) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Event

Contract authority for GET /v1/events/{id} (getEvent) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Upload Event Documents

Contract authority for POST /v1/events/{event_id}/documents (uploadEventDocuments) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
event_id
required
string

Path parameter event_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.

Responses

Retained Claim Compatibility Submit

Compatibility contract for retained POST /v1/claims (submitClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility List

Compatibility contract for retained GET /v1/claims (listClaims) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Get

Compatibility contract for retained GET /v1/claims/{id} (getClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Retained Claim Compatibility Assess

Compatibility contract for retained POST /v1/claims/{id}/assess (assessClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; the route assesses the contract-facing assertion for the retained claim-family surface. Claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Pay

Compatibility contract for retained POST /v1/claims/{id}/pay (payClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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
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

authorisation_id
string or null

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
{
  • "paid_amount": {
    },
  • "payment_method": "bank_transfer",
  • "payment_notes": "Final settlement — retained assertion fully resolved",
  • "authorisation_id": "clm_01abcdefghjkmnpqrstvwxyz01",
  • "metadata": {
    }
}

Response samples

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

Create Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves (createReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Reserve List

Compatibility contract for retained GET /v1/claims/{id}/reserves (listClaimReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Get Reserve

Compatibility contract for retained GET /v1/claims/{id}/reserves/{reserveId} (getReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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

Update Reserve

Compatibility contract for retained PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Release Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Cancel Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Reestablish Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

List Policy Reserves

Compatibility contract for retained GET /v1/claims/reserves (listPolicyReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Or Advance Investigation

Compatibility contract for retained POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Recovery

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries (createRecovery) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

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.

Responses

Create Correction

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

recoveryId
required
string

Path parameter recoveryId.

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.

Responses

Retained Claim Compatibility Get Settlement Statement

Compatibility contract for retained GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

decisionId
required
string

Path parameter decisionId.

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

List Assertions

Contract authority for GET /v1/assertions (listAssertions) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Assertion

Contract authority for GET /v1/assertions/{id} (getAssertion) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Receive Inbox Message

Contract authority for POST /v1/inbox/messages (receiveInboxMessage) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Webhook Delivery Status

Contract authority for GET /v1/mailroom/outbox/webhook-deliveries/{delivery_id} (getWebhookDeliveryStatus) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
delivery_id
required
string

Path parameter delivery_id.

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

contract-authority

List Events

Contract authority for GET /v1/events (listEvents) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Event

Contract authority for GET /v1/events/{id} (getEvent) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Upload Event Documents

Contract authority for POST /v1/events/{event_id}/documents (uploadEventDocuments) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
event_id
required
string

Path parameter event_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.

Responses

Retained Claim Compatibility Submit

Compatibility contract for retained POST /v1/claims (submitClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility List

Compatibility contract for retained GET /v1/claims (listClaims) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Get

Compatibility contract for retained GET /v1/claims/{id} (getClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Retained Claim Compatibility Assess

Compatibility contract for retained POST /v1/claims/{id}/assess (assessClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; the route assesses the contract-facing assertion for the retained claim-family surface. Claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Pay

Compatibility contract for retained POST /v1/claims/{id}/pay (payClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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
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

authorisation_id
string or null

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
{
  • "paid_amount": {
    },
  • "payment_method": "bank_transfer",
  • "payment_notes": "Final settlement — retained assertion fully resolved",
  • "authorisation_id": "clm_01abcdefghjkmnpqrstvwxyz01",
  • "metadata": {
    }
}

Response samples

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

Create Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves (createReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Reserve List

Compatibility contract for retained GET /v1/claims/{id}/reserves (listClaimReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Get Reserve

Compatibility contract for retained GET /v1/claims/{id}/reserves/{reserveId} (getReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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

Update Reserve

Compatibility contract for retained PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Release Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Cancel Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Reestablish Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

List Policy Reserves

Compatibility contract for retained GET /v1/claims/reserves (listPolicyReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Or Advance Investigation

Compatibility contract for retained POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Recovery

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries (createRecovery) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

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.

Responses

Create Correction

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

recoveryId
required
string

Path parameter recoveryId.

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.

Responses

Retained Claim Compatibility Get Settlement Statement

Compatibility contract for retained GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

decisionId
required
string

Path parameter decisionId.

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

List Assertions

Contract authority for GET /v1/assertions (listAssertions) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Assertion

Contract authority for GET /v1/assertions/{id} (getAssertion) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Receive Inbox Message

Contract authority for POST /v1/inbox/messages (receiveInboxMessage) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Webhook Delivery Status

Contract authority for GET /v1/mailroom/outbox/webhook-deliveries/{delivery_id} (getWebhookDeliveryStatus) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
delivery_id
required
string

Path parameter delivery_id.

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

audit-remediation

List Events

Contract authority for GET /v1/events (listEvents) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Event

Contract authority for GET /v1/events/{id} (getEvent) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Upload Event Documents

Contract authority for POST /v1/events/{event_id}/documents (uploadEventDocuments) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
event_id
required
string

Path parameter event_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.

Responses

Retained Claim Compatibility Submit

Compatibility contract for retained POST /v1/claims (submitClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility List

Compatibility contract for retained GET /v1/claims (listClaims) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Get

Compatibility contract for retained GET /v1/claims/{id} (getClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Retained Claim Compatibility Assess

Compatibility contract for retained POST /v1/claims/{id}/assess (assessClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; the route assesses the contract-facing assertion for the retained claim-family surface. Claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Pay

Compatibility contract for retained POST /v1/claims/{id}/pay (payClaim) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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
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

authorisation_id
string or null

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
{
  • "paid_amount": {
    },
  • "payment_method": "bank_transfer",
  • "payment_notes": "Final settlement — retained assertion fully resolved",
  • "authorisation_id": "clm_01abcdefghjkmnpqrstvwxyz01",
  • "metadata": {
    }
}

Response samples

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

Create Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves (createReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Retained Claim Compatibility Reserve List

Compatibility contract for retained GET /v1/claims/{id}/reserves (listClaimReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Get Reserve

Compatibility contract for retained GET /v1/claims/{id}/reserves/{reserveId} (getReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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

Update Reserve

Compatibility contract for retained PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Release Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Cancel Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

Reestablish Reserve

Compatibility contract for retained POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

reserveId
required
string

Path parameter reserveId.

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.

Responses

List Policy Reserves

Compatibility contract for retained GET /v1/claims/reserves (listPolicyReserves) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Or Advance Investigation

Compatibility contract for retained POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Create Recovery

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries (createRecovery) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

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.

Responses

Create Correction

Compatibility contract for retained POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
claimId
required
string

Path parameter claimId.

recoveryId
required
string

Path parameter recoveryId.

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.

Responses

Retained Claim Compatibility Get Settlement Statement

Compatibility contract for retained GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) in the Events/Assertions portfolio. Axiom canon is events/assertions; claim-family route names, operationIds, permission scopes, generated filenames, and SDK-facing identifiers are retained compatibility identifiers until a governed migration. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

decisionId
required
string

Path parameter decisionId.

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

List Assertions

Contract authority for GET /v1/assertions (listAssertions) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Assertion

Contract authority for GET /v1/assertions/{id} (getAssertion) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

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

Receive Inbox Message

Contract authority for POST /v1/inbox/messages (receiveInboxMessage) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

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.

Responses

Get Webhook Delivery Status

Contract authority for GET /v1/mailroom/outbox/webhook-deliveries/{delivery_id} (getWebhookDeliveryStatus) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.

Authorizations:
BearerAuth
path Parameters
delivery_id
required
string

Path parameter delivery_id.

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

Tenant Schema

Register a new schema definition

Creates a new schema definition in draft state. The schema must pass content validation (valid JSON object, canonical field names under the governed contract) before it can be published.

Requires actor attribution 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
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

Schema name (e.g. 'motor_vehicle')

scope
required
string
Value: "tenant"

Tenant self-service schema scope

entity_type
required
string
Enum: "party" "party_role" "party_contact" "party_identity" "party_relationship" "party_group" "party_group_membership" "product" "product_term" "cover" "cover_item" "cover_term" "cover_item_term" "policy" "policy_version" "event" "assertion" "assertion_line"

Target entity type

entity_sub_type
string

Required for subtype-governed entity types. The schema name must be <entity_type>.<entity_sub_type>.

required
object

Schema body as JSON object with canonical field names

required
object
compatibility
required
string
Enum: "backward" "forward" "breaking"

Compatibility classification under the governed contract

predecessor_schema_id
string

ID of the predecessor schema version for lineage tracking

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string
deprecation_target_at
string <date-time>

Optional target date for future deprecation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scope": "tenant",
  • "entity_type": "party",
  • "entity_sub_type": "string",
  • "content": { },
  • "version": {
    },
  • "compatibility": "backward",
  • "predecessor_schema_id": "string",
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string",
  • "deprecation_target_at": "2019-08-24T14:15:22Z"
}

Response samples

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

List schema definitions with cursor pagination

Returns paginated schema definitions filtered by optional criteria. Uses cursor-based pagination under the governed contract. Legacy limit/offset pagination is rejected with 400.

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

Number of results per page (default 25, max 100)

page[after]
string

Cursor token for next page (from previous response meta)

name
string

Filter by schema name

state
string
Enum: "draft" "published" "deprecated"

Filter by lifecycle state

scope
string
Value: "tenant"

Filter by scope

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": {
    },
  • "status": "string"
}

Resolve a schema by name and semantic version

Looks up a specific schema definition by name and exact semantic version triplet. Returns 404 with SCHEMA_NOT_FOUND if no match exists.

Authorizations:
BearerAuth
query Parameters
name
required
string

Schema name to resolve

version
required
string
Example: version=1.0.0

Semantic version in major.minor.patch format

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 a schema definition by ID

Retrieves a single schema definition by its opaque schema identifier. Scoped to the tenant from the request context.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string

Opaque schema definition 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"
}

Publish a draft schema

Transitions a schema from draft to published state. Requires expected_version for optimistic concurrency control.

Before publication, validates:

  • Schema content (JSON object, canonical field names)
  • Compatibility classification
  • Platform schema compatibility (for tenant-scoped schemas)

Published schemas are immutable — content, version, and compatibility cannot be changed after publication under the governed contract.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string
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
expected_version
required
integer

Current version for optimistic locking

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string

Responses

Request samples

Content type
application/json
{
  • "expected_version": 0,
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string"
}

Response samples

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

Deprecate a published schema

Transitions a schema from published to deprecated state. Requires a reason and expected_version for optimistic concurrency control.

Deprecation is idempotent — deprecating an already-deprecated schema returns success with the current state.

Deprecated schemas remain queryable but are marked as superseded. Published records are never deleted or mutated under the governed contract.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string
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
expected_version
required
integer

Current version for optimistic locking

reason
required
string

Reason for deprecation

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string

Responses

Request samples

Content type
application/json
{
  • "expected_version": 0,
  • "reason": "string",
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string"
}

Response samples

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

Schema Registry

Register a new schema definition

Creates a new schema definition in draft state. The schema must pass content validation (valid JSON object, canonical field names under the governed contract) before it can be published.

Requires actor attribution 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
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

Schema name (e.g. 'motor_vehicle')

scope
required
string
Value: "tenant"

Tenant self-service schema scope

entity_type
required
string
Enum: "party" "party_role" "party_contact" "party_identity" "party_relationship" "party_group" "party_group_membership" "product" "product_term" "cover" "cover_item" "cover_term" "cover_item_term" "policy" "policy_version" "event" "assertion" "assertion_line"

Target entity type

entity_sub_type
string

Required for subtype-governed entity types. The schema name must be <entity_type>.<entity_sub_type>.

required
object

Schema body as JSON object with canonical field names

required
object
compatibility
required
string
Enum: "backward" "forward" "breaking"

Compatibility classification under the governed contract

predecessor_schema_id
string

ID of the predecessor schema version for lineage tracking

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string
deprecation_target_at
string <date-time>

Optional target date for future deprecation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scope": "tenant",
  • "entity_type": "party",
  • "entity_sub_type": "string",
  • "content": { },
  • "version": {
    },
  • "compatibility": "backward",
  • "predecessor_schema_id": "string",
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string",
  • "deprecation_target_at": "2019-08-24T14:15:22Z"
}

Response samples

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

List schema definitions with cursor pagination

Returns paginated schema definitions filtered by optional criteria. Uses cursor-based pagination under the governed contract. Legacy limit/offset pagination is rejected with 400.

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

Number of results per page (default 25, max 100)

page[after]
string

Cursor token for next page (from previous response meta)

name
string

Filter by schema name

state
string
Enum: "draft" "published" "deprecated"

Filter by lifecycle state

scope
string
Value: "tenant"

Filter by scope

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": {
    },
  • "status": "string"
}

Resolve a schema by name and semantic version

Looks up a specific schema definition by name and exact semantic version triplet. Returns 404 with SCHEMA_NOT_FOUND if no match exists.

Authorizations:
BearerAuth
query Parameters
name
required
string

Schema name to resolve

version
required
string
Example: version=1.0.0

Semantic version in major.minor.patch format

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 a schema definition by ID

Retrieves a single schema definition by its opaque schema identifier. Scoped to the tenant from the request context.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string

Opaque schema definition 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"
}

Publish a draft schema

Transitions a schema from draft to published state. Requires expected_version for optimistic concurrency control.

Before publication, validates:

  • Schema content (JSON object, canonical field names)
  • Compatibility classification
  • Platform schema compatibility (for tenant-scoped schemas)

Published schemas are immutable — content, version, and compatibility cannot be changed after publication under the governed contract.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string
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
expected_version
required
integer

Current version for optimistic locking

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string

Responses

Request samples

Content type
application/json
{
  • "expected_version": 0,
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string"
}

Response samples

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

Deprecate a published schema

Transitions a schema from published to deprecated state. Requires a reason and expected_version for optimistic concurrency control.

Deprecation is idempotent — deprecating an already-deprecated schema returns success with the current state.

Deprecated schemas remain queryable but are marked as superseded. Published records are never deleted or mutated under the governed contract.

Authorizations:
BearerAuth
path Parameters
schema_id
required
string
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
expected_version
required
integer

Current version for optimistic locking

reason
required
string

Reason for deprecation

actor_type
required
string
Enum: "human" "service" "agent"
actor_id
required
string
actor_original_id
required
string

Responses

Request samples

Content type
application/json
{
  • "expected_version": 0,
  • "reason": "string",
  • "actor_type": "human",
  • "actor_id": "string",
  • "actor_original_id": "string"
}

Response samples

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