API docs by Redocly

Axiom Platform API (0.1.64)

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, claims analysis, revenue trends, and product performance.

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

Get dashboard metrics

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Get claims breakdown by status

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Get monthly revenue trend

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Get top products by premium volume

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Audit

Audit trail — recent audit entries for compliance and debugging.

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

Get recent audit entries

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

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

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

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

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

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

subject_type
string
Example: subject_type=policy

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

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

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

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

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

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

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

Responses

Response samples

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

Benefit

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

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

Apply Proration Adjustment

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

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

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

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

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

product_id
required
string

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

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

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

Responses

Request samples

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

Response samples

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

Get benefit balance

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

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

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

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

Policy UUID to query benefits for

benefit_type
required
string
Example: benefit_type=hospitalisation

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

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

Start of the benefit period (ISO 8601 date)

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

End of the benefit period (ISO 8601 date)

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

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

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

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

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

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

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

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

Responses

Response samples

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

Get available benefit amount

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

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

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

Policy UUID to query benefit availability for

benefit_type
required
string
Example: benefit_type=dental

Benefit type identifier

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

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

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

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

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

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

Responses

Response samples

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

Get Proration Balance

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

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

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

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

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

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

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

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

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

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

Responses

Response samples

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

Benefit claims-ratio route under schema reconciliation

This route is intentionally unavailable in alpha. It remains present for route accountability, but consumers must use the benefit balance and available-benefit routes until the claims-ratio aggregation has a canonical claim-item implementation.

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

Correlation id for request tracing.

Responses

Response samples

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

Get catalogue

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

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

Authorizations:
BearerAuth
path Parameters
catalogue-ref
required
string

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

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

List bi-temporal entries

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

Optional filters:

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

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

query Parameters
as_of
string <date-time>

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

recorded_at
string <date-time>

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

logical_entry_id
string <uuid>

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

code
string

Exact code match filter.

q
string

Keyword search on the entry description field.

order_by
string

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

dir
string
Enum: "asc" "desc"

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

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

Atomically create N relationships in one transaction

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

Authorizations:
BearerAuth
path Parameters
catalogue-ref
required
string

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

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

Responses

Request samples

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

Response samples

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

Claim

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

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

Record a claim authorisation

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

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

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

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

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

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

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

transition_kind
required
string

Sector-neutral transition verb.

authorisation_kind
required
string

Tenant-keyed authorisation kind.

authorising_actor
required
string <uuid>

Party-in-role actor that granted the authorisation.

object

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

budget_minor
integer or null <int64>

Exact integer minor units for the authorised budget ceiling.

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

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

governing_version_kind
string or null

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

governing_version_row_id
string or null <uuid>

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

compliance_kind
string or null

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

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

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

compliance_list_version
string or null

Tenant-supplied as-was list or standard version.

compliance_list_authority
string or null

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

decision_date
required
string <date-time>

Moment the authorisation decision was made.

explanation_node_id
required
string <uuid>

Explanation-node reference for the authorisation decision.

finding_reference
string or null <uuid>

Required by the persistence rule on revoke or withdrawal transitions.

Responses

Request samples

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

Response samples

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

Close a claim

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

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

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
closure_reason
string

Reason for closing the claim

closed_by
string

Identifier of the user or system closing the claim

Responses

Request samples

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

Response samples

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

Generate a claim PDF report

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

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

The generated PDF includes:

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

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

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

Unique claim identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get claim audit trail

Returns the tenant-scoped audit trail for the claim after verifying the claim exists for the operating tenant.

Authorizations:
BearerAuth
path Parameters
id
required
string

Resource identifier.

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 <uuid>
Example: 6b6487c1-bf44-5a61-ad58-caf256e207b6

Compliance evaluation UUID

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

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

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

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

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

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

Responses

Response samples

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

Contract

Generated OpenAPI contract served by the deployed API binary.

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

Get the deployed OpenAPI contract

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

Responses

Response samples

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

Get the deployed OpenAPI contract

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

Responses

Response samples

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

Get async job status

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

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

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

UUID of the async job to poll.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

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

Event

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

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

List Events

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

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

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

Responses

Request samples

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

Response samples

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

Submit Claim

Contract authority for POST /v1/claims (submitClaim) 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

List Claims

Contract authority for GET /v1/claims (listClaims) 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 Claim

Contract authority for GET /v1/claims/{id} (getClaim) 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

Assess Claim

Contract authority for POST /v1/claims/{id}/assess (assessClaim) 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).

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

Pay Claim

Contract authority for POST /v1/claims/{id}/pay (payClaim) 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).

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 Reserve

Contract authority for POST /v1/claims/{id}/reserves (createReserve) 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).

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

Contract authority for GET /v1/claims/{id}/reserves (listClaimReserves) 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

Get Reserve

Contract authority for GET /v1/claims/{id}/reserves/{reserveId} (getReserve) 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.

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

Contract authority for PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) 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.

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

Contract authority for GET /v1/claims/reserves (listPolicyReserves) 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

Create Or Advance Investigation

Contract authority for POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) 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).

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

Contract authority for POST /v1/claims/{claimId}/recoveries (createRecovery) 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
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

Contract authority for POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) 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
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

Get Claim Settlement Statement

Contract authority for GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) 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.

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

Correlation id for request tracing.

Responses

Response samples

Content type
application/json
{}

Upload an object to the archive

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

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

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

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

The binary payload to archive.

original_filename
string

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

mime_type
string

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

source
string

Provenance tag (default "api").

Responses

Response samples

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

Report Event

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

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

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

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

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

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

property name*
additional property
string <binary>

Responses

Response samples

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

Create an evidence record

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

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

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

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

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

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

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

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

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

Request Body schema: application/json
required
record_type
required
string

Classification of the evidence record

subject_type
required
string

Type of the entity this evidence pertains to

subject_id
required
string

Identifier of the subject entity

required
object

Structured evidence payload

created_by
string

Identifier of the creating user or service

Responses

Request samples

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

Response samples

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

Get an evidence record by ID

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

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

Evidence record UUID

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

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

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

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

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

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

Responses

Response samples

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

Query evidence records

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

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

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

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

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

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

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

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

Request Body schema: application/json
required
subject_type
string

Filter by subject type

subject_id
string

Filter by subject identifier

record_type
string

Filter by evidence record type

from_date
string <date-time>

Filter records created on or after this timestamp

to_date
string <date-time>

Filter records created before this timestamp

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of records to return

offset
integer >= 0
Default: 0

Number of records to skip

Responses

Request samples

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

Response samples

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

Verify integrity of a single evidence record

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

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

Evidence record UUID to verify

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

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

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

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

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

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

Responses

Response samples

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

Batch-verify evidence record integrity

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

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

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

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

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

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

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

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

List of evidence record IDs to verify

Responses

Request samples

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

Response samples

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

Assemble an evidence pack

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

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

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

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

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

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

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

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

Request Body schema: application/json
required
name
required
string

Descriptive name for the evidence pack

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

List of evidence record IDs to include in the pack

assembled_by
string

Identifier of the user or service assembling the pack

Responses

Request samples

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

Response samples

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

Get an evidence pack by ID

Returns an evidence pack including all constituent evidence records.

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

Evidence pack UUID

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

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

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

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

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

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

Responses

Response samples

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

Health

Service health and readiness checks. No authentication required.

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

Check API health

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

Responses

Response samples

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

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

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

Request correlation ID for tracing

Responses

Response samples

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

Create a ledger entry reversal

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

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

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

Ledger entry UUID to reverse

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
reason
required
string

Reason for the reversal (required for audit trail)

posted_by
required
string

User or service authorising the reversal

entry_date
string <date-time>

Accounting date for the reversal (defaults to now)

Responses

Request samples

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

Response samples

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

Verify ledger integrity

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

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

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

Restrict verification to specific accounts (all if omitted)

date_from
string <date-time>

Start of verification period

date_to
string <date-time>

End of verification period

Responses

Request samples

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

Response samples

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

List ledger entries for the tenant

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

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

Authorizations:
BearerAuth
query Parameters
reference_id
string

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

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

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

page[after]
string

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Get corrections for a ledger entry

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

Results sorted by created_at descending.

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

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

Original ledger entry UUID

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Party

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

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

List available party role types

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

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Role-type usage counts

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Register Party

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

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

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

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

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

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

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

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

external_id
string

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

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

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

required
object

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

created_by
string

Identifier of the user or service creating this party

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

Current Party lifecycle status.

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

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

Responses

Request samples

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

Response samples

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

List parties

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

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

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

Maximum number of parties to return in this cursor page.

page[after]
string

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

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

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

external_id
string

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

q
string >= 3 characters

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

role
string

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get a party by ID

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

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

Unique party identifier

query Parameters
as_of
string <date-time>

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

recorded_at
string <date-time>

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Update a party

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

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
external_id
string

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

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

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

object or null

Updated party-specific data. Merged with existing attributes.

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

Current Party lifecycle status.

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

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

updated_by
string

Identifier of the user or service performing the update

Responses

Request samples

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

Response samples

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

Get roles assigned to a party

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Assign a role to a party

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

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
role_type
required
string

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

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

The type of entity this role is scoped to

entity_id
required
string <typed-prefix-id>

The identifier of the entity this role is scoped to

assigned_by
required
string

Identifier of the user or service assigning this role

object or null

Optional attributes for the role assignment

Responses

Request samples

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

Response samples

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

List contacts for a party

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Add a contact to a party

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

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

Email address

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

Phone number in E.164 format

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

Preferred contact method

Responses

Request samples

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

Response samples

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

Update a party contact

Update an existing contact record for a party.

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

Unique party identifier

contactId
required
string <typed-prefix-id>

Unique contact identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

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

Email address

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

Phone number in E.164 format

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

Preferred contact method

Responses

Request samples

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

Response samples

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

Delete a party contact

Remove a contact record from a party.

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

Unique party identifier

contactId
required
string <typed-prefix-id>

Unique contact identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

List identity documents for a party

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Add an identity document to a party

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
identity_type
required
string

Type of identity document

identity_value
required
string

The identity document number or value

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

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

expiry_date
string or null <date>

Expiry date of the identity document

Responses

Request samples

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

Response samples

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

Verify a party identity document

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

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

Unique party identifier

identityId
required
string <typed-prefix-id>

Unique identity document identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
verification_method
string

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

verified_by
string

Identifier of the user or service performing verification

notes
string or null

Optional notes about the verification

Responses

Request samples

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

Response samples

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

List relationships for a party

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

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

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

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

Unique party identifier

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

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

as_of
string <date-time>

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

relationship_type
string

Comma-separated tenant catalogue.relationship_types code filter.

max_depth
integer [ 1 .. 16 ]

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Create a relationship between two parties

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

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

Unique party identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

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

Target party for the relationship

relationship_type
required
string

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

effective_from
string or null <date-time>

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

effective_to
string or null <date-time>

Relationship expiry timestamp. Null means open-ended.

object or null

Optional key-value metadata for the relationship

Responses

Request samples

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

Response samples

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

Delete (deactivate) a party relationship

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

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

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

Unique party identifier

relId
required
string <typed-prefix-id>

Unique relationship identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
reason
required
string

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

Responses

Request samples

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

Response samples

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

List party groups containing this party

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

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

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

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

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

Responses

Response samples

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

List the policy-driven groups a party belongs to

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

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

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

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

List payments for a party

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

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

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

Unique party identifier

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

Maximum number of payments to return

page[after]
string

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Chronological audit feed for a party

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

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

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

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

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

page[after]
string

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

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

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

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

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

Responses

Response samples

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

Revoke a party role

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

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

Unique party identifier

roleId
required
string <typed-prefix-id>

Party role assignment identifier to revoke.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get a party balance

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

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

Unique party identifier

query Parameters
product_id
string <typed-prefix-id>

Limit the balance to entries associated with this product.

policy_id
string <typed-prefix-id>

Limit the balance to entries associated with this policy.

cover_id
string <typed-prefix-id>

Limit the balance to entries associated with this cover.

category
string

Limit the balance to a ledger category.

role
string

Limit the balance to a tenant catalogue.role_types code.

as_of
string <date-time>

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

decompose
boolean
Default: false

Include balance computation explanation details when true.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Party Group

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

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

List party groups containing this party

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

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

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

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

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

Responses

Response samples

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

Chronological audit feed for a party group

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

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

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

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

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

page[after]
string

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

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

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

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

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

Responses

Response samples

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

List party groups

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

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

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

page[after]
string

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

q
string >= 3 characters

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

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

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

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

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

Responses

Response samples

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

Create a party group

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

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

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

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

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

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

Defaults to static when omitted

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

Required when group_type = dynamic

Responses

Request samples

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

Response samples

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

Get a party group with its active members

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

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

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

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

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

Responses

Response samples

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

Update display_name / description / status

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

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

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

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

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

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

Responses

Request samples

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

Response samples

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

Soft delete (status → inactive)

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

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

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

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

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

Responses

Response samples

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

Add a party or group as a member

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

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

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

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

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

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

Defaults to now() server-side when omitted

Responses

Request samples

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

Response samples

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

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

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

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

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

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

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

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

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

Responses

Response samples

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

List all party members reachable via recursive expansion

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

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

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

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

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

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

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

Responses

Response samples

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

List groups that transitively contain this group

BFS upward through the membership DAG up to max_depth.

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

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

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

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

Responses

Response samples

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

List groups transitively contained by this group

BFS downward through the membership DAG up to max_depth.

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

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

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

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

Responses

Response samples

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

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

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

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

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

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

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

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

Defaults to now() server-side

Responses

Request samples

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

Response samples

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

List roles held directly by this group

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

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

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

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

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

Responses

Response samples

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

Assign a role to the group

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

For role_type=accepted_provider_network:

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

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

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

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

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

Responses

Request samples

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

Response samples

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

Revoke a role held by the group

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

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

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

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

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

Request Body schema: application/json
optional
reason
string

Responses

Request samples

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

Response samples

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

Payment

Payment processing — payment records and payment schedule management. Supports bank transfer, credit card, debit order, and other methods. Status: pending → processing → completed → failed → cancelled.

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

List payments for a party

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

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

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

Unique party identifier

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

Maximum number of payments to return

page[after]
string

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

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

List payments

Retrieves a cursor-paginated list of payments for the current tenant.

Results are sorted by created_at descending with id as a stable tie-breaker.

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

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

Maximum number of items to return (default 20, max 100)

page[after]
string

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Create a payment

Creates a new payment record in pending status.

The payment is not processed immediately. Use the POST /v1/payments/{id}/process endpoint to initiate processing.

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

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

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

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

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

Request correlation ID for tracing

Request Body schema: application/json
required
required
object

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

payment_method
required
string (PaymentMethod)
Enum: "bank_transfer" "credit_card" "debit_order" "cash" "cheque"

Supported payment methods:

  • bank_transfer — Electronic funds transfer (EFT) or wire transfer
  • credit_card — Credit card payment via payment gateway
  • debit_order — Recurring debit order (direct debit) from bank account
  • cash — Cash payment (recorded manually, typically at branch)
  • cheque — Cheque payment (subject to clearing period)
description
string or null

Human-readable description of the payment purpose

reference_id
string or null <uuid>

Reference to the associated resource (premium, claim, etc.)

reference_type
string or null

Type of the referenced resource

party_id
string or null <uuid>

Reference to the party associated with this payment. Must be a valid party ID within the tenant.

object or null

Extensible key-value metadata

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "payment_method": "bank_transfer",
  • "description": "Annual premium — liability professional indemnity POL-2026-00789",
  • "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7",
  • "reference_type": "premium",
  • "party_id": "07805e66-69d7-5b42-a978-32729404b560",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment created successfully"
}

Get a payment by ID

Retrieves a single payment by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Update a payment

Updates a payment record. Only payments in pending status can be updated.

Fields that can be updated: amount, currency, payment_method, description, reference_id, reference_type, metadata.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
object

Updated payment amount (exact integer minor units + lowercase ISO-4217 currency code).

payment_method
string (PaymentMethod)
Enum: "bank_transfer" "credit_card" "debit_order" "cash" "cheque"

Supported payment methods:

  • bank_transfer — Electronic funds transfer (EFT) or wire transfer
  • credit_card — Credit card payment via payment gateway
  • debit_order — Recurring debit order (direct debit) from bank account
  • cash — Cash payment (recorded manually, typically at branch)
  • cheque — Cheque payment (subject to clearing period)
description
string or null

Updated human-readable description

reference_id
string or null <uuid>

Updated reference to associated resource

reference_type
string or null

Updated type of referenced resource

object or null

Updated extensible metadata

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "payment_method": "debit_order",
  • "description": "Adjusted monthly premium — motor comprehensive policy POL-2026-00123",
  • "reference_id": "97c1ff22-6e4f-4821-b1d3-5236781d37b8",
  • "reference_type": "string",
  • "metadata": { }
}

Response samples

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

Process a payment

Initiates processing for a pending payment.

Transitions the payment through the lifecycle: pending -> processing -> completed (or failed).

This is an asynchronous operation. The response confirms the payment has been submitted for processing. Poll the payment status or use webhooks to track completion.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

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

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

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

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

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

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment submitted for processing"
}

Cancel a payment

Cancels a payment. Only payments in pending or processing status can be cancelled.

Transitions the payment to cancelled status. This action cannot be undone.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: fc07471c-677f-5d54-b3b0-4172aacb0fcd

Payment UUID identifier

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

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

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

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

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

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Payment cancelled successfully"
}

List payment schedules

Retrieves a cursor-paginated list of payment schedules for the current tenant.

Results are derived from aggregate Premium rows and sorted by effective_date descending with id as a stable tie-breaker.

Payment schedules define recurring cadence obligations tied to policies (e.g. monthly debit orders for motor premiums, quarterly bank transfers for property cover). The list surface reports cadence definitions; per- instalment paid/overdue state belongs to the payment settlement surface.

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

Maximum number of payment schedules to return in this page.

page[after]
string

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "status": "success",
  • "message": "Payment schedules retrieved successfully"
}

Create a payment schedule

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

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
policy_id
required
string <uuid>

Reference to the policy this schedule services

frequency
required
string (PaymentFrequency)
Enum: "monthly" "quarterly" "half_yearly" "annual"

Payment schedule frequency:

  • monthly — Payment due every month
  • quarterly — Payment due every 3 months
  • half_yearly — Payment due every 6 months
  • annual — Payment due once per year
amount
required
integer <int64> >= 0

Scheduled payment amount per period in the smallest currency unit (e.g. cents). Exact integer representation.

currency
required
string^[A-Z]{3}$

ISO 4217 currency code

next_due_date
required
string <date>

First scheduled payment date

Responses

Request samples

Content type
application/json
{
  • "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd",
  • "frequency": "half_yearly",
  • "amount": 420000,
  • "currency": "EUR",
  • "next_due_date": "2026-06-01"
}

Response samples

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

Get a payment schedule by ID

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

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Pause a payment schedule

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

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Resume a paused payment schedule

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

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 24161ecd-8592-537c-849c-575aea8b40f1

Payment schedule UUID identifier

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

List invoices with cursor pagination

Retrieves a paginated list of invoices for the current tenant using cursor-based pagination under the governed contract.

Legacy offset-based pagination (limit/offset query params) is rejected with 400 LEGACY_PAGINATION.

Results sorted by created_at descending.

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

Maximum number of items to return (default 25, max 100)

page[after]
string

Cursor for the next page (invoice ID from previous response)

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

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get a single invoice by ID

Retrieves a single invoice by its unique identifier. Returns 404 for unknown IDs or cross-tenant access attempts.

Authorizations:
BearerAuth
path Parameters
id
required
string

Invoice identifier

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

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Finalize an invoice

Finalizes a draft invoice, making it immutable. Requires actor attribution headers under the governed contract.

Authorizations:
BearerAuth
path Parameters
id
required
string

Invoice identifier

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

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

X-Actor-ID
required
string

Actor identifier (governed contract)

X-Actor-Type
required
string
Enum: "human" "service" "agent"

Actor type (governed contract)

Responses

Response samples

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

Close a billing cycle

Closes a billing cycle for the specified period, generating an invoice. Requires actor attribution headers under the governed contract.

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

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

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

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

X-Correlation-ID
string

Request correlation ID for tracing

X-Actor-ID
required
string

Actor identifier (governed contract)

X-Actor-Type
required
string
Enum: "human" "service" "agent"

Actor type (governed contract)

Request Body schema: application/json
required
period_start
required
string <date-time>

Start of the billing period (RFC3339)

period_end
required
string <date-time>

End of the billing period (RFC3339)

idempotency_key
string

Optional idempotency key for deduplication

Responses

Request samples

Content type
application/json
{
  • "period_start": "2026-03-01T00:00:00Z",
  • "period_end": "2026-03-31T23:59:59Z",
  • "idempotency_key": "string"
}

Response samples

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

Policy

Policy lifecycle — creation, versioning, endorsements, and status transitions. A policy binds a product to parties with specific terms and coverage dates. Status: draft → active → suspended → cancelled → expired → lapsed.

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

Initiate a policy replacement

Starts a replacement workflow that supersedes one or more existing policies with a replacement policy. Returns the initial workflow state including the allowed transitions from the starting step.

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

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
policy_id
required
string

The replacement policy id (typed-prefix wire form).

existing_policy_ids
required
Array of strings

Policies being superseded by this replacement.

jurisdiction_code
required
string

ISO 3166-1 alpha-2 jurisdiction code (lowercase).

required
object (replacementActor)
reason
required
string

Human-intelligible justification (audit trail).

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

object

Optional caller-supplied metadata.

Responses

Request samples

Content type
application/json
{
  • "policy_id": "pol_01j1234567890abcdefghijk",
  • "existing_policy_ids": [
    ],
  • "jurisdiction_code": "za",
  • "actor": {
    },
  • "reason": "Customer requested upgrade to comprehensive cover",
  • "occurred_at": "2026-06-02T12:00:00Z"
}

Response samples

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

Get a replacement workflow

Fetch the current state of a replacement workflow by id.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

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

Advance a replacement workflow

Advances the workflow to the next step, supplying the evidence payload required by the current step. Optimistic-concurrency via version.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
required
object (replacementActor)
reason
required
string

Human-intelligible justification for the advance.

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

required
object

Step-specific evidence required to advance.

version
required
integer

Optimistic-concurrency version of the workflow being advanced.

Responses

Request samples

Content type
application/json
{
  • "actor": {
    },
  • "reason": "Replacement disclosure acknowledged",
  • "occurred_at": "2026-06-02T12:05:00Z",
  • "evidence_payload": {
    },
  • "version": 1
}

Response samples

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

Cancel a replacement workflow

Cancels an in-flight replacement workflow. Optimistic-concurrency via version.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Request Body schema: application/json
required
required
object (replacementActor)
reason
required
string

Human-intelligible cancellation justification.

occurred_at
required
string <date-time>

Business-event timestamp (RFC 3339).

version
required
integer

Optimistic-concurrency version of the workflow being cancelled.

Responses

Request samples

Content type
application/json
{
  • "actor": {
    },
  • "reason": "Customer withdrew request",
  • "occurred_at": "2026-06-02T12:10:00Z",
  • "version": 1
}

Response samples

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

Get replacement evidence

Returns the evidence collected per step for a replacement workflow.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: prp_01j1234567890abcdefghijk

Replacement workflow identifier (prp_ typed-prefix).

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string <uuid>

Correlation id for request tracing.

Responses

Response samples

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

Apply Proration Adjustment

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

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

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

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

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

product_id
required
string

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

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

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

Responses

Request samples

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

Response samples

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

Create a new policy

Issue a new insurance policy under an active product. The policy is created in "draft" status by default. At least one party must be assigned (typically the policyholder). Draft policies are not endorsement-eligible; use POST /v1/policies/bind to create an active, endorsement-eligible policy.

The product must be in "active" status before policies can be issued against it. The effective date must not be in the past (backdating requires special permissions).

Side effects: persists the policy in draft status with assigned parties; emits an audit entry recording the creation.

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
product_id
required
string <uuid>

Identifier of the product to issue the policy under

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": "e74fc507-ba17-5540-871a-0b04cdb6727b",
  • "effective_date": "2026-04-01",
  • "expiry_date": "2027-03-31",
  • "attributes": {
    },
  • "parties": [
    ],
  • "created_by": "agent-user-012"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy created successfully"
}

List policies

Retrieve a cursor-paginated list of policies for the tenant. Results are sorted by most-recently-recorded first. Sort order is not configurable. Legacy limit and offset query parameters are rejected.

Returns policies across all statuses (draft, quoted, bound, active, lapsed, cancelled, expired).

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

Maximum number of policies to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

party_id
string

Optional filter — return only policies the party is bound to in any role (the party appears in policy.parties). Accepts the canonical typed-prefix party id (pty_…, governed contract). A malformed value returns 400. Absent = all policies for the tenant (current behaviour). Composes with the existing operating-tenant tenant-isolated scope; never widens it.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Bind Policy

Bind parties to covers through an active policy version. This contract is the primary policy-creation operation — it reads party and 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 <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Create a new policy version

Create a new version snapshot of the policy. Policy versions provide an immutable record of the policy state at each point in time, supporting "as-was" semantics required for claims adjudication and regulatory reporting.

Each version captures the complete policy state including attributes, parties, and coverage details at the time of creation.

Side effects: not yet implemented. Returns 501.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
effective_date
required
string <date>

Date from which this version takes effect

reason
string

Reason for creating a new version

created_by
string

Identifier of the user or service creating this version

Responses

Request samples

Content type
application/json
Example
{
  • "effective_date": "2026-06-01",
  • "reason": "Mid-term adjustment — sum insured increase from 250,000 to 300,000",
  • "created_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy version created successfully"
}

List policy version snapshots

Return every immutable version snapshot for the policy, ordered by version_number ascending.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Issue a draft policy

Transition a policy from draft to bound status. The policy must have at least one party with the policyholder role assigned.

Side effects: persists the status change and emits an audit entry with operation code policy.issue in a single transaction.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
issued_by
required
string

Identifier of the user or service issuing the policy

notes
string

Optional notes for the issue action

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy issued successfully"
}

Activate a bound policy

Transition a policy from bound to active status. The policy's effective date must be in the past or present (effective_date <= now).

Side effects: persists the status change and emits an audit entry with operation code policy.activate in a single transaction.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
activated_by
required
string

Identifier of the user or service activating the policy

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Policy activated successfully"
}

Create a policy endorsement

Submit an endorsement (mid-term adjustment) to an active policy. Endorsements record structured changes to the policy terms, coverage, or parties. The policy must be in active status; endorsing a draft or other non-active policy returns HTTP 422 with code INVALID_STATE_TRANSITION.

Each endorsement receives a sequential number within the policy (END-001, END-002, etc.) and triggers the creation of a new policy version when applied.

Side effects: creates a new immutable policy version and persists party-role changes when change_type=parties. Emits an audit entry when audit is configured.

Common endorsement types:

  • amendment: Modify existing terms (e.g. change address, increase sum insured)
  • addition: Add new coverage or parties
  • deletion: Remove coverage or parties
  • correction: Fix data entry errors
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
change_type
required
string
Enum: "parties" "coverages" "terms" "premium"

Classification of the endorsement change

description
required
string

Human-readable description of the changes

Array of objects

New parties to add (for change_type 'parties')

object or null

Structured representation of attribute changes

endorsed_by
required
string

Identifier of the user or process creating the endorsement

effective_at
string <date-time>

Effective timestamp for party endorsements (change_type=parties). Must not be retroactive. Required when change_type=parties.

Array of objects

Party mutations for change_type=parties endorsements. Each entry specifies an operation (add/revoke/replace), party_id, and role.

Responses

Request samples

Content type
application/json
Example
{
  • "change_type": "coverages",
  • "description": "Increase vehicle insured value following market revaluation",
  • "updated_attributes": {
    },
  • "endorsed_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Endorsement created successfully"
}

List policy endorsements

Return the policy's endorsements, ordered by version_number ascending. Endorsements are stored as policy version snapshots (no separate entity); this list is the policy's versions filtered to version_type == endorsement.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get member certificate projection

Retrieve a read-only certificate of insurance for a specific member on a group policy. Resolves the effective policy version and active roles at the as_of timestamp (defaults to now). Returns the master policy_id, party_id, role list, effectivity window, and pinned version_id.

No persistence side effects — this is a pure read projection.

Returns 404 if the party is unknown or inactive at the given as_of time.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique policy identifier

party_id
required
string

Identifier of the member party

query Parameters
as_of
string <date-time>

Point-in-time for certificate resolution (defaults to now)

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Certificate retrieved successfully"
}

Create a new quote

Creates a persisted premium calculation (quote) with a 30-minute TTL. Exactly one of pricing_snapshot_id, products, or product_id must be provided.

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
pricing_snapshot_id
string

Reference to a prior rate result snapshot (mutually exclusive with products)

Array of objects

Inline product + risk_profile pairs (mutually exclusive with pricing_snapshot_id)

product_id
string

Legacy single-product shorthand (backward compatible)

effective_date
required
string <date>
expiry_date
required
string <date>
object
covers_selected
Array of strings
Default: []
comparison_ref
string

Links comparison sets for quote comparison

supersedes
string

Quote ID this quote supersedes

Array of objects (QuoteParty)

Party snapshot for bind-time matching

Responses

Request samples

Content type
application/json
{
  • "pricing_snapshot_id": "string",
  • "products": [
    ],
  • "product_id": "string",
  • "effective_date": "2026-04-01",
  • "expiry_date": "2027-04-01",
  • "underwriting_data": {
    },
  • "covers_selected": [ ],
  • "comparison_ref": "string",
  • "supersedes": "string",
  • "parties": [
    ]
}

Response samples

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

List quotes by comparison reference

Returns all quotes for a given comparison_ref, ordered by created_at DESC. Tenant-scoped to prevent cross-tenant leakage.

Authorizations:
BearerAuth
query Parameters
comparison_ref
required
string

Comparison reference to filter quotes

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Retrieve a quote by ID

Returns the persisted quote if active. Returns 404 for unknown IDs (including cross-tenant lookups) and 410 Gone for expired quotes.

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Approve a quote (indicative to firm)

Transitions a quote from indicative to firm status. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Decline a quote

Transitions a quote to declined status. Requires a reason_code. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
reason_code
required
string

Machine-readable reason for declining the quote

Responses

Request samples

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

Response samples

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

Bind a firm quote to create a policy

Binds a firm quote, creating a policy, premium allocation, ledger entries, and explanation tree. Only firm quotes can be bound. Requires actor attribution (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Idempotency-Key
required
string

Idempotency key for bind operations (required under the governed contract)

Request Body schema: application/json
required
payment_method
required
string
bound_by
required
string
Array of objects (QuoteParty)

Bind-time parties (must match quote snapshot if provided)

Responses

Request samples

Content type
application/json
{
  • "payment_method": "string",
  • "bound_by": "string",
  • "parties": [
    ]
}

Response samples

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

Get quote supersession chain

Returns the full supersession chain for a quote, ordered oldest-first. Walks backward through supersedes_quote_id links and reverses.

Authorizations:
BearerAuth
path Parameters
id
required
string

Quote identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Get Proration Balance

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

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

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

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

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

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

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

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

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

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

Responses

Response samples

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

Premium

Premium management — billing records and premium calculation engine. Includes standalone premium CRUD and product-based calculation with adjustments and commission breakdowns.

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

Apply Proration Adjustment

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

Authorizations:
BearerAuth
path Parameters
id
required
string

Path parameter id.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

Idempotency-Key
required
string

Idempotency key (scope: tenant).

X-Correlation-ID
string

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

Request Body schema: application/json
required
policy_id
required
string

Policy identity in wire form.

premium_id
string

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

product_id
required
string

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

proration_intent
required
string

Tenant ruleset key that declares what adjustment intent to evaluate.

reason
string <= 1024 characters

Operator-supplied reason for the adjustment request.

correction_of_decision_id
string <uuid>

Existing proration decision UUID corrected by this decision.

required
object
required
object
object

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

Responses

Request samples

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

Response samples

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

Simulate an allocation breakdown

Validates a proposed allocation breakdown without persisting it. Accepts only simulation_preview as trigger. Returns 422 for semantic validation failures (sum mismatch, missing rule_id, invalid inputs).

Each operation in the request specifies a benefit change (add, remove, change) with proposed allocation values in allocation_inputs.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Policy identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List temporal allocation history for a policy

Returns cursor-paginated temporal allocation snapshots for all premiums in a policy. Ordered by effective_from DESC, created_at DESC, premium_id ASC. Uses half-open [effective_from, effective_to) temporal semantics under the governed contract.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Policy identifier

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

Number of resources per page

page[after]
string

Cursor for forward pagination (allocation ID)

page[before]
string

Cursor for backward pagination (allocation ID)

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "meta": {
    }
}

List premiums

Retrieve a paginated list of aggregate premium records for the operating tenant (one Premium per policy, the contract model). Cursor-paginated with page[size] default 20 / max 100 and opaque page[after] cursors. Legacy limit and offset query parameters are rejected.

The policy_id / party_id filter parameters are validated fail-loud (a malformed typed-prefix value returns 400, governed contract); they compose with the operating-tenant tenant-isolated scope, never widen it.

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

Maximum number of premiums to return in this cursor page

page[after]
string

Opaque cursor returned as meta.next_cursor by the previous page

policy_id
string

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

party_id
string

Optional filter — return only premiums owed by this party (the premium debtor / policyholder). Accepts the canonical typed-prefix party id (pty_…, governed contract). A malformed value returns 400. Absent = all premiums for the tenant. Composes with the existing operating-tenant tenant-isolated scope; never widens it.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Create a premium record

Persist a new aggregate premium (inflow-obligation) record for a policy and return it with 201 Created. Exactly one Premium exists per policy (the (tenant context, policy_id) uniqueness constraint, the contract model) — a create for a policy that already has a premium fails loud with 409 Conflict.

This persists a manually-entered / imported inflow-obligation record at status=draft. It is NOT a rated premium decision — the rated path is POST /v1/premiums/calculate, which evaluates versioned CEL rules and emits an explanation tree. A draft obligation carries no rating decision to explain (platform principle untouched).

The premium is scoped to the operating tenant — tenant context is taken from the tenant-context, never the request body. Intentional defaults applied on create (documented, not silent): status=draft, premium_type defaults to initial, and an unrated draft sets base_premium = net_premium = final_premium = amount.amount_minor (no discounts/commission yet, contract rule).

Idempotent via the Idempotency-Key header: same key + same body returns the original 201; same key + different body returns 409.

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

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
policy_id
required
string

Reference to the policy this premium belongs to, in the canonical typed-prefix form (pol_…, governed contract). A bare UUID is also accepted. A malformed value returns 400.

required
object

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

premium_type
string

Optional classifier on the aggregate premium (defaults to initial when omitted, contract rule). E.g. initial, renewal, endorsement, adjustment.

party_id
string

Optional reference to the party who owes this premium, in the canonical typed-prefix form (pty_…, governed contract). A bare UUID is also accepted. A malformed value returns 400.

Responses

Request samples

Content type
application/json
Example
{
  • "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a",
  • "amount": {
    },
  • "premium_type": "initial"
}

Response samples

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

Get a premium by ID

Retrieve a single premium record by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique premium identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Calculate a premium quotation

Calculate a premium quotation for a given product and risk 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 risk 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 quoting workflows 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 <uuid>

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-motor-001",
  • "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b",
  • "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 <uuid>

Unique premium identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

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

Premium identifier

query Parameters
as_of
string <date-time>

Point-in-time for temporal query (RFC3339). Defaults to now.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Get Proration Balance

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

Authorizations:
BearerAuth
query Parameters
policy_id
required
string

Policy ID in pol_ wire form.

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

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

period_start
required
string <date-time>

Inclusive balance period start.

period_end
required
string <date-time>

Exclusive balance period end.

fund_account_code
string

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

account_code
string

Generic account code for fund or earning balance scope.

earning_period_key
string

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

decompose
boolean
Default: false

Include constituent proration component IDs and operation details.

header Parameters
X-Tenant-Context
required
string

Operating-tenant context (binding: operating_tenant).

X-Correlation-ID
string

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

Responses

Response samples

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

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

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Update a product

Update an existing product's metadata, attributes, or status. Products can be transitioned from "draft" to "active" status via this endpoint.

Updating an active product creates a new version. Existing policies issued under previous versions are not affected.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated display name

description
string

Updated description

status
string
Enum: "draft" "active"

Updated product status

object or null

Updated extensible attributes (merged with existing)

Responses

Request samples

Content type
application/json
Example
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Product updated successfully"
}

Get coverage sections for a product

Retrieve all coverage sections (covers) defined for a product. Each cover includes its sum insured, deductible, type (basic/optional/rider), and any associated cover provision definitions and terms.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Add a coverage section (cover) to a product

CRS-3: add a cover to a draft product. The cover may carry nested cover_items (each with terms) and cover-level cover_terms, persisted as the full canonical cover.* row graph in one atomic transaction. Money boundaries are exact integer minor units with a lowercase ISO-4217 currency; a monetary boundary missing its currency is rejected (422). Co-insurance panel splits (basis points) must sum to 10000bp (100%) or the request is rejected (422).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string

Short code for this coverage section

name
required
string

Display name

description
string

Detailed description of coverage

type
required
string
Enum: "basic" "optional" "rider"

Coverage type within the product

sum_insured
integer or null <int64>

Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.

deductible
integer or null <int64>

Excess amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.

object or null

Extensible attributes

Array of objects or null (AddCoverItemRequest)

CRS-3: nested cover items, each with its own terms. Persisted as the full canonical cover.* row graph in one atomic transaction.

Array of objects or null (AddCoverTermRequest)

CRS-3: nested cover-level terms (conditions, limits, exclusions).

Responses

Request samples

Content type
application/json
{
  • "code": "TPL-BODILY",
  • "name": "Third-Party Bodily Injury",
  • "description": "Covers liability for bodily injury to third parties arising from vehicle use",
  • "type": "basic",
  • "sum_insured": 100000000,
  • "deductible": 50000,
  • "attributes": { },
  • "cover_items": [
    ],
  • "cover_terms": [
    ]
}

Response samples

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

Bind a product to a ruleset version for a pipeline stage

Creates or supersedes the active product↔ruleset binding for the given ruleset_type (pipeline stage). under the governed contract a single product carries one binding per (tenant context, product_id, ruleset_type, effective_from); binding a different ruleset_type does NOT close the prior stage's active row — supersession is per-stage.

ruleset_type is REQUIRED and must be in the canonical allowlist (see 400 INVALID_RULESET_TYPE body for the accepted set). Earlier runtime behaviour silently defaulted the field to claims_assessment at the persistence boundary. The current contract rejects missing or unknown values at the HTTP boundary with the accepted set listed in the error body.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
required
ruleset_id
required
string <uuid>

ID of the ruleset to bind to the product

ruleset_type
required
string

Pipeline stage the binding satisfies. Must be in the canonical allowlist; see 400 INVALID_RULESET_TYPE response for the full set.

ruleset_version
required
integer >= 1

Version number of the bound ruleset

effective_from
required
string <date>

Date this binding becomes active (YYYY-MM-DD)

Responses

Request samples

Content type
application/json
{
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "ruleset_type": "premium_rating",
  • "ruleset_version": 1,
  • "effective_from": "2026-01-01"
}

Response samples

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

List product↔ruleset bindings (active and historical)

Returns the binding history for a product in deterministic order (effective_from DESC, created_at DESC, id DESC). Each item includes ruleset_type so callers can distinguish stages without re-querying.

Optional ?ruleset_type= filter narrows the response to a single stage. Unknown values are rejected with 400 INVALID_RULESET_TYPE (no silent empty-list).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

query Parameters
ruleset_type
string

Filter by pipeline stage; must be in the canonical allowlist

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Activate a draft product

Transition a product from draft to active status. The product must have at least one cover and defined terms (with explicit validation bounds) before activation.

This is a status-only transition: it does NOT re-persist the product's cover graph, so it never collides on existing covers (unlike a full PUT update). Side effects: persists the status change and emits a formal activation explanation tree (governed contract).

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Request Body schema: application/json
optional
activated_by
string
Deprecated

Retired compatibility field. Product activation attribution is derived from the authenticated actor context and this value is ignored.

Responses

Request samples

Content type
application/json
{
  • "activated_by": "usr_3f8a"
}

Response samples

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

Chronological audit feed for a product

Returns the per-product audit feed in descending performed-at order. The feed is scoped to the admitted tenant context, verifies that the product exists before reading audit rows, and never returns a silent empty feed for an unknown product identifier.

Use limit and offset for the current bounded alpha page contract. The runtime default is 50 rows from offset 0.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Unique product identifier

query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

Maximum number of audit entries to return.

offset
integer >= 0
Default: 0

Zero-based audit entry offset.

header Parameters
X-Tenant-Context
required
string

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

X-Correlation-ID
string

Request correlation ID for tracing

Responses

Response samples

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

Report

Report generation and export (PDF, CSV).

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

Export a report

Generates and exports a report in the requested format (PDF or CSV).

Supported report types:

  • premium_collection — Premium collection summary by product and period
  • claims_register — Claims register with status, amounts, and settlement details
  • loss_ratio — Loss ratio analysis by product line
  • policy_register — Policy register with coverage and premium details
  • reconciliation — Ledger reconciliation report
  • commission_statement — Broker commission statement

The response is the report file itself (binary content), not a JSON envelope.

Authorizations:
BearerAuth
query Parameters
type
required
string
Enum: "premium_collection" "claims_register" "loss_ratio" "policy_register" "reconciliation" "commission_statement"
Example: type=premium_collection

Report type to generate

format
required
string
Enum: "pdf" "csv"
Example: format=pdf

Output format for the report

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

Start date for the report period (inclusive, ISO 8601 date)

date_to
string <date>
Example: date_to=2026-03-31

End date for the report period (inclusive, ISO 8601 date)

product_code
string
Example: product_code=motor-comprehensive

Filter report to a specific product code

currency
string^[A-Z]{3}$
Example: currency=USD

Currency for monetary amounts (defaults to tenant base currency)

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Ruleset

Business rules engine — rulesets, rules, testing, and deployment. Rules are data.: explicit, versioned, deterministic, auditable. Supports CEL expressions, conditions, and actions.

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

Create a ruleset

Creates a new ruleset in draft status.

Rulesets are versioned containers of business rules that govern domain rule lanes such as underwriting, pricing, claims assessment, document completeness, or discount composition. Rules are data. — explicit, versioned, deterministic, and auditable.

Optionally specify a base_ruleset code to inherit rules from an existing ruleset as a starting point.

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string

Machine-readable ruleset code (must be unique within the tenant)

name
required
string

Human-readable ruleset name

entity_type
required
string
Enum: "claims" "underwriting" "pricing" "claims_assessment" "document_completeness" "discount"

Runtime rule lane this ruleset governs

description
required
string

Detailed description of the ruleset purpose

object or null

Optional metadata (jurisdiction, product line, etc.)

base_ruleset
string or null

Code of an existing ruleset to use as a template. The new ruleset inherits rules from the base, which can then be overridden or extended.

Responses

Request samples

Content type
application/json
{
  • "code": "health-gap-ng-v1",
  • "name": "Nigeria Health Gap Cover",
  • "entity_type": "pricing",
  • "description": "Pricing rules for health gap cover in Nigeria",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Ruleset created successfully"
}

List rulesets

Retrieves a paginated list of rulesets for the current tenant.

Results are sorted by recorded_at descending with the ruleset id as a stable cursor tiebreaker. Legacy limit and offset query parameters are rejected; use page[size] and page[after].

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

Maximum number of items to return (default 20, max 100)

page[after]
string
Example: page[after]=eyJyZWNvcmRlZF9hdCI6IjIwMjYtMDgtMTVUMTI6MDA6MDBaIiwiaWQiOiJiMWMyZDNlNC1mNWE2LTc4OTAtYmNkZS1mMTIzNDU2Nzg5MDEifQ

Opaque cursor returned as meta.next_cursor from the previous page

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

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

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

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

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

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

Get a ruleset by ID

Retrieves a single ruleset by its unique identifier, including all associated business rules.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

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

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

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

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a ruleset

Updates the metadata of a ruleset (name, description, attributes).

Only rulesets in draft status can be updated. Active or deprecated rulesets are immutable — create a new version instead.

This does not modify individual rules. Use the rule-level endpoints to add, update, or remove rules.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated human-readable name

description
string

Updated description

object or null

Updated metadata

Responses

Request samples

Content type
application/json
{
  • "name": "Motor Vehicle Rating Rules (Updated)",
  • "description": "Validation, pricing, and eligibility rules for comprehensive motor insurance",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Test a ruleset against input facts

Evaluates the entire ruleset against the provided input facts and returns the evaluation results.

This is a dry-run — no state is modified. The response includes a full explanation tree showing which rules fired, their inputs, intermediate results, and final decisions (platform principle explainability).

The ruleset must be active before this endpoint runs. Testing a draft ruleset returns 409 RULESET_NOT_ACTIVE; use /test-rule for isolated expression checks while authoring.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
required
object

Input facts for rule evaluation. Structure depends on the ruleset's entity_type and the rules defined within it.

Responses

Request samples

Content type
application/json
{
  • "facts": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Test a single rule within a ruleset

Evaluates a single rule expression against the provided input facts. Useful for iterative rule development and debugging before the rule is added to a ruleset.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
expression
required
string

CEL expression to test.

required
object

Input facts for rule evaluation

Responses

Request samples

Content type
application/json
{
  • "expression": "applicant.age >= 18",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Deploy a ruleset

Transitions a ruleset from draft to active status, making it available for evaluation in live policy, claim, and premium workflows.

This increments the ruleset version number. The previous active version (if any) is transitioned to deprecated and retained for as-was auditability.

This operation cannot be undone — to roll back, deploy the previous version's rules in a new ruleset.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
activated_by
required
string

Actor identifier recorded in the deployment audit trail.

Responses

Request samples

Content type
application/json
{
  • "activated_by": "underwriter-user-003"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "success",
  • "message": "Ruleset deployed successfully"
}

Add a rule to a ruleset

Adds a new business rule to a ruleset. The ruleset must be in draft status.

Rules are defined as CEL (Common Expression Language) expressions that must be deterministic and side-effect free.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
code
required
string <= 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)

Structured conditions evaluated before the expression

Array of objects or null (RuleAction)

Actions to execute when the rule evaluates to true

Responses

Request samples

Content type
application/json
{
  • "code": "max-vehicle-age",
  • "name": "Maximum Vehicle Age",
  • "rule_type": "validation",
  • "expression": "vehicle.year_of_manufacture >= 2011",
  • "description": "Vehicle must be no more than 15 years old for comprehensive cover in the test year",
  • "priority": 20,
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Update a rule within a ruleset

Updates an existing business rule within a ruleset. The ruleset must be in draft status.

Updatable fields: name, expression, description, priority, status, attributes, conditions, actions.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

ruleId
required
string <uuid>
Example: 0b601f31-c78a-5246-92a7-2ed20988ebfe

Rule UUID identifier within the ruleset

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Request Body schema: application/json
required
name
string

Updated rule name

expression
string

Updated CEL expression

description
string or null

Updated description

priority
integer

Updated execution priority

status
string
Enum: "draft" "active" "deprecated"

Updated rule status

object or null

Updated metadata

Array of objects or null (RuleCondition)
Array of objects or null (RuleAction)

Responses

Request samples

Content type
application/json
{
  • "name": "Maximum Vehicle Age (Extended)",
  • "expression": "vehicle.year_of_manufacture >= 2006",
  • "description": "Vehicle must be no more than 20 years old for extended comprehensive cover",
  • "priority": 20,
  • "status": "draft",
  • "attributes": { },
  • "conditions": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Delete a rule from a ruleset

Removes a rule from a ruleset. The ruleset must be in draft status.

Rules in active or deprecated rulesets cannot be deleted — deprecate the rule instead to preserve the audit trail.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 7ffab4d3-56e1-548b-a116-a577714722cd

Ruleset UUID identifier

ruleId
required
string <uuid>
Example: 0b601f31-c78a-5246-92a7-2ed20988ebfe

Rule UUID identifier within the ruleset

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string <uuid>

Request correlation ID for tracing

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": { },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

Vendor

Vendor registry and risk management (governed contract). Tracks vendors, integrations, data access, and subprocessor approvals.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Register a new vendor

Creates a vendor record for a third-party service provider.

Vendors represent external organisations that process, store, or access tenant data. Each vendor is tracked for compliance purposes (POPIA, GDPR) including data classification, security review status, and subprocessor chains.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List vendors

Returns a paginated list of vendor records for the tenant.

Supports cursor-based pagination via page[size] and page[after] query parameters. Response uses a JSON:API-style collection envelope with data array and meta object.

Authorizations:
BearerAuth
query Parameters
page[size]
integer [ 1 .. 100 ]
Default: 20

Maximum number of vendors to return (default 20, max 100)

page[after]
string

Opaque cursor for next page; obtained from previous response meta.next_cursor

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a vendor by ID

Returns the full vendor record including integrations and subprocessors. Response uses JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Vendor UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a vendor

Partially updates a vendor record. Only provided fields are modified. Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Vendor UUID identifier

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a subprocessor to a vendor

Registers a subprocessor under a vendor. Subprocessors are third parties that the vendor engages to process data on behalf of the tenant.

Tracking subprocessors is required for POPIA and GDPR compliance, ensuring the full data processing chain is documented and approved.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Parent vendor UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a subprocessor

Partially updates a subprocessor record under a vendor. Typically used to change approval status or update service scope.

Request and response use JSON:API envelope format.

Authorizations:
BearerAuth
path Parameters
vendor_id
required
string <uuid>
Example: f9f3f72a-0a08-5807-be2f-69be9dfbe595

Parent vendor UUID

subprocessor_id
required
string <uuid>
Example: d3216bd6-21dd-572a-8396-9e1444af9bfb

Subprocessor UUID

header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhook

Outbound webhook dispatch (governed contract). Register webhook endpoints and track delivery status. Uses JSON:API response format.

Public maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.

Register a webhook endpoint

Registers or updates a tenant-scoped outbound webhook endpoint.

This is an alpha transport-configuration surface governed by the Mailroom transport registry, not an ordinary product API operation. It records where outbound webhook deliveries may be sent and how the delivery should be authenticated. Event subscription catalogues and delivery routing rules are not yet published as a public self-service contract. Do not send event_types, event schemas, routing rules, ordering keys, or replay policy in this request; those semantics are governed separately before publication.

Secrets are supplied by reference only. Do not send raw secret material in the request body.

For auth_method=hmac_sha256, each outbound delivery includes:

  • X-Axiom-Delivery-Id: typed whd_ durable delivery id.
  • X-Correlation-ID: support trace id for the delivery workflow.
  • X-Webhook-Timestamp: Unix seconds in UTC.
  • X-Webhook-Signature: sha256=<hex> where the digest is HMAC-SHA256(secret, X-Webhook-Timestamp + "." + raw request body bytes).

Receivers should reject missing, malformed, stale, or mismatched signatures before processing the payload. A five-minute replay window is the alpha recommendation unless the issued integration runbook specifies a stricter tenant policy.

Outbound webhook delivery is at-least-once. Exactly-once delivery, global ordering, and per-endpoint ordering are not guaranteed in the alpha public contract. The same X-Axiom-Delivery-Id is reused across retry attempts for one delivery record, but it is not a stable canonical event id across endpoints, event streams, or schema revisions. Receivers must be idempotent and tolerate duplicate, delayed, and out-of-order deliveries.

Response format: Canonical success envelope.

Authorizations:
BearerAuth
header Parameters
X-Tenant-Context
required
string
Example: <tenant-context token from POST /v1/me/tenant-context>

Server-minted tenant-context token (TCT) in request header.

Required for all tenant-scoped requests. Obtain it from POST /v1/me/tenant-context after discovering accessible tenants via GET /v1/me/tenants. The TCT is a short-lived HMAC-signed token that carries the selected tenant and the authenticated account subject; the client-supplied tenant selectors are not accepted.

The API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.

X-Correlation-ID
string
Example: req-abc-123-def-456

Request correlation ID for end-to-end tracing. If not provided, the server generates one automatically. The response always includes this header for support reference.

Request Body schema: application/json
required
name
required
string [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]+$

Tenant-scoped endpoint name. Reusing the same name updates mutable endpoint settings.

url
required
string <uri>

HTTPS endpoint URL where webhook payloads will be delivered. Runtime validation rejects non-HTTPS URLs and known private, loopback, link-local, and non-routable targets.

description
string

Human-readable description of this endpoint's purpose.

auth_method
required
string
Default: "hmac_sha256"
Enum: "hmac_sha256" "bearer_token_ref" "none"

Authentication method for webhook deliveries.

  • hmac_sha256: HMAC signature over timestamp and raw body bytes.
  • bearer_token_ref: bearer token resolved from auth_secret_ref at dispatch time.
  • none: unsigned delivery; admitted only where tenant policy allows it.
auth_secret_ref
string

Opaque secret reference resolved by the Mailroom dispatcher. Required when auth_method is hmac_sha256 or bearer_token_ref. Raw secret material must not be sent in this field.

enabled
boolean
Default: true

Whether the endpoint is active

max_retries
required
integer [ 0 .. 10 ]

Number of retry attempts after the first delivery attempt.

backoff_seconds
required
Array of integers[ items [ 1 .. 3600 ] ]

Retry backoff values in seconds. The array length must equal max_retries; each value must be between 1 and 3600 seconds.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "primary-events",
  • "url": "https://receiver.example.com/axiom/webhooks",
  • "description": "Primary outbound event receiver",
  • "auth_method": "hmac_sha256",
  • "auth_secret_ref": "ref:webhooks/primary-events-signing-key",
  • "max_retries": 3,
  • "backoff_seconds": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "message": "string",
  • "meta": { },
  • "links": { },
  • "telemetry": { }
}

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

Submit Claim

Contract authority for POST /v1/claims (submitClaim) 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

List Claims

Contract authority for GET /v1/claims (listClaims) 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 Claim

Contract authority for GET /v1/claims/{id} (getClaim) 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

Assess Claim

Contract authority for POST /v1/claims/{id}/assess (assessClaim) 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).

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

Pay Claim

Contract authority for POST /v1/claims/{id}/pay (payClaim) 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).

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 Reserve

Contract authority for POST /v1/claims/{id}/reserves (createReserve) 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).

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 Claim Reserves

Contract authority for GET /v1/claims/{id}/reserves (listClaimReserves) 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

Get Reserve

Contract authority for GET /v1/claims/{id}/reserves/{reserveId} (getReserve) 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.

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

Contract authority for PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) 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.

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

Contract authority for GET /v1/claims/reserves (listPolicyReserves) 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

Create Or Advance Investigation

Contract authority for POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) 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).

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

Contract authority for POST /v1/claims/{claimId}/recoveries (createRecovery) 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
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

Contract authority for POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) 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
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

Get Claim Settlement Statement

Contract authority for GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) 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.

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

Submit Claim

Contract authority for POST /v1/claims (submitClaim) 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

List Claims

Contract authority for GET /v1/claims (listClaims) 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 Claim

Contract authority for GET /v1/claims/{id} (getClaim) 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

Assess Claim

Contract authority for POST /v1/claims/{id}/assess (assessClaim) 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).

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

Pay Claim

Contract authority for POST /v1/claims/{id}/pay (payClaim) 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).

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 Reserve

Contract authority for POST /v1/claims/{id}/reserves (createReserve) 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).

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 Claim Reserves

Contract authority for GET /v1/claims/{id}/reserves (listClaimReserves) 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

Get Reserve

Contract authority for GET /v1/claims/{id}/reserves/{reserveId} (getReserve) 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.

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

Contract authority for PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) 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.

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

Contract authority for GET /v1/claims/reserves (listPolicyReserves) 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

Create Or Advance Investigation

Contract authority for POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) 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).

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

Contract authority for POST /v1/claims/{claimId}/recoveries (createRecovery) 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
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

Contract authority for POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) 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
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

Get Claim Settlement Statement

Contract authority for GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) 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.

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

Submit Claim

Contract authority for POST /v1/claims (submitClaim) 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

List Claims

Contract authority for GET /v1/claims (listClaims) 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 Claim

Contract authority for GET /v1/claims/{id} (getClaim) 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

Assess Claim

Contract authority for POST /v1/claims/{id}/assess (assessClaim) 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).

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

Pay Claim

Contract authority for POST /v1/claims/{id}/pay (payClaim) 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).

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 Reserve

Contract authority for POST /v1/claims/{id}/reserves (createReserve) 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).

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 Claim Reserves

Contract authority for GET /v1/claims/{id}/reserves (listClaimReserves) 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

Get Reserve

Contract authority for GET /v1/claims/{id}/reserves/{reserveId} (getReserve) 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.

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

Contract authority for PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) 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.

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

Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) 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.

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

Contract authority for GET /v1/claims/reserves (listPolicyReserves) 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

Create Or Advance Investigation

Contract authority for POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) 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).

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

Contract authority for POST /v1/claims/{claimId}/recoveries (createRecovery) 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
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

Contract authority for POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) 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
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

Get Claim Settlement Statement

Contract authority for GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) 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.

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