{ "openapi": "3.0.3", "info": { "title": "Axiom Platform API", "description": "Axiom is programmable insurance infrastructure: one engine for every line of\ninsurance, where the rules are data and every decision can be explained to the\nperson it affects.\n\n## Overview\n\nAxiom provides a complete REST API across the five universal insurance\nprimitives \u2014 parties/roles, products/covers, policies/versions,\npremiums/payments, and events/assertions (under the governed contract). Every feature is\ndesigned API-first under the governed contract.\n\n## Authentication\n\nAll API requests (except health checks) require:\n- **Bearer token** via `Authorization` header (JWT from auth service)\n- **Tenant context** via `X-Tenant-Context` header (server-minted token, required on tenant-scoped endpoints)\n\n## Response Format\n\nMost endpoints currently return a legacy envelope format:\n```json\n{\n \"data\": { ... },\n \"status\": \"success\",\n \"message\": \"optional description\"\n}\n```\n\nError responses:\n```json\n{\n \"error\": \"Human-readable error message\",\n \"status\": \"error\"\n}\n```\n\nNewer endpoints (inbox, ingress, webhooks, vendors) use the JSON:API format\nunder the governed contract. Migration of legacy endpoints to JSON:API is planned.\n\n## Pagination\n\nList endpoints declare their pagination profile per operation. Newer\nconverged list endpoints use cursor-based pagination:\n- `page[size]` \u2014 maximum items per page\n- `page[after]` \u2014 opaque cursor from the previous page\n\nLegacy alpha list endpoints may still use offset-based pagination until\nthey are migrated:\n- `limit` \u2014 maximum items per page\n- `offset` \u2014 number of items to skip\n\nCursor response metadata includes `has_more` and may include `next_cursor`.\nOffset response metadata includes `total`, `limit`, and `offset`.\n\nExample offset metadata:\n```json\n{\n \"data\": [...],\n \"meta\": { \"total\": 150, \"limit\": 20, \"offset\": 0 },\n \"status\": \"success\"\n}\n```\n\n## Correlation Tracing\n\nInclude `X-Correlation-ID` header for end-to-end request tracing.\nIf omitted, the server generates one. The response always includes\n`X-Correlation-ID` for support reference.\n\n## Versioning\n\nAPI families are in the URL path (`/v1/...`). The published contract\nversion is SemVer and is emitted in `info.version`, `X-API-Version`, and\nresponse telemetry under the governed contract.\n\n## Rate Limiting\n\nWhen a tenant-scoped route has an active runtime rate-limit policy,\nresponses include budget headers:\n- `X-RateLimit-Limit` \u2014 active tenant policy limit for the route\n- `X-RateLimit-Remaining` \u2014 remaining requests in the current window\n- `X-RateLimit-Reset` \u2014 window reset time (Unix timestamp)\n\nRejected calls return `429` with `Retry-After`.\n", "version": "0.1.22", "contact": { "name": "Axiom Platform Team", "email": "hello@axiom.express" }, "license": { "name": "Proprietary", "url": "https://axiom.express/license" } }, "servers": [ { "url": "https://api.afr-dev.axiom.express", "description": "Africa developer preview" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Analytics", "description": "Dashboard metrics, claims analysis, revenue trends, and product performance.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Assertion", "description": "Assertions \u2014 the per-event contract-response record (the canonical\nevents/assertions paired primitive, governed contract). Read-only surface\n(GET + LIST). Lifecycle: pending \u2192 settled \u2192 reopened \u2192 adjusted \u2192 finalised.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Audit", "description": "Audit trail \u2014 recent audit entries for compliance and debugging.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Benefit", "description": "Benefit balance computation (governed contract). Parameterised queries for\nbenefit utilisation, available balance, and usage decomposition.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Catalogue", "description": "Catalogue parent lifecycle, bi-temporal entries, temporal values, relationships, labels, descriptor, source provenance, and bulk-write operations. Governed by governed contract.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Claim", "description": "Claims processing \u2014 submission, assessment, payment, and closure.\nStatus: submitted \u2192 assessing \u2192 assessed \u2192 approved \u2192 paying \u2192 paid \u2192 closed.\nAlso: submitted \u2192 rejected \u2192 closed.\nDeprecated (RFC-8594; Sunset 2026-08-31) in favour of Assertion.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Compliance", "description": "Compliance evaluation engine (governed contract). Evaluates subjects against\nregulatory requirements and produces compliance reports.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Contract", "description": "Generated OpenAPI contract served by the deployed API binary.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Event", "description": "Event and assertion workflows exposed in the developer-preview API.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Evidence", "description": "Evidence records and packs for audit and compliance (governed contract).\nTamper-evident records with content hashing and integrity verification.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Health", "description": "Service health and readiness checks. No authentication required.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Identity", "description": "Authenticated actor, admitted tenant discovery, and tenant-context bootstrap.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Inbox", "description": "Inbound message ingestion (governed contract). Durable, idempotent message\nintake with deduplication. Uses JSON:API response format.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ingress", "description": "Async event ingestion (governed contract). Conditionally available event intake with\ntransformation pipeline support. Uses JSON:API response format.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ledger", "description": "Double-entry accounting ledger \u2014 entries, transactions, account balances,\nreversals, integrity verification, and reconciliation. Supports as-of\ntemporal queries with explanation traces.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Party", "description": "Party management \u2014 individuals, organisations, brokers, agents, and providers.\nParties are the actors in the insurance lifecycle (policyholders, claimants,\nbeneficiaries, underwriters).\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Party Group", "description": "Composable party-grouping primitive under the governed contract. Groups can contain\nparties and other groups (polymorphic DAG membership), support static\nand dynamic (CEL-rule-driven) membership, and can hold roles in their\nown right without inheriting to member parties. Distinct from Policy\nGroup (governed contract) which groups policies for cover application.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Payment", "description": "Payment processing \u2014 payment records and payment schedule management.\nSupports bank transfer, credit card, debit order, and other methods.\nStatus: pending \u2192 processing \u2192 completed \u2192 failed \u2192 cancelled.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Policy", "description": "Policy lifecycle \u2014 creation, versioning, endorsements, and status transitions.\nA policy binds a product to parties with specific terms and coverage dates.\nStatus: draft \u2192 active \u2192 suspended \u2192 cancelled \u2192 expired \u2192 lapsed.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Premium", "description": "Premium management \u2014 billing records and premium calculation engine.\nIncludes standalone premium CRUD and product-based calculation with\nadjustments and commission breakdowns.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Product", "description": "Insurance product catalogue \u2014 product definitions, covers, cover provisions,\nterms, pricing rules, and commissions. Products are templates from which\npolicies are created. Supports motor, property, health, life, liability, and more.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Report", "description": "Report generation and export (PDF, CSV).\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ruleset", "description": "Business rules engine \u2014 rulesets, rules, testing, and deployment.\nRules are data.: explicit, versioned, deterministic, auditable.\nSupports CEL expressions, conditions, and actions.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Vendor", "description": "Vendor registry and risk management (governed contract). Tracks vendors,\nintegrations, data access, and subprocessor approvals.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Webhook", "description": "Outbound webhook dispatch (governed contract). Register webhook endpoints\nand track delivery status. Uses JSON:API response format.\n\nPublic 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.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } } ], "paths": { "/openapi": { "get": { "operationId": "getOpenAPIContract", "summary": "Get the deployed OpenAPI contract", "description": "Returns the generated OpenAPI 3 contract embedded in the running API binary.\nThe SHA-256 digest of this exact document is exposed on `/v1/health` under\n`contract.sha256` for deployed-contract verification.\n", "tags": [ "Contract" ], "security": [], "responses": { "200": { "description": "Generated OpenAPI 3 contract for the deployed API binary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true, "properties": { "openapi": { "type": "string", "pattern": "^3\\.", "example": "3.0.3" }, "info": { "type": "object", "additionalProperties": true }, "paths": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Contract endpoint not found (misconfigured route).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/openapi": { "get": { "operationId": "getVersionedOpenAPIContract", "summary": "Get the deployed OpenAPI contract", "description": "Versioned alias for `/openapi`. Returns the generated OpenAPI 3 contract\nembedded in the running API binary.\n", "tags": [ "Contract" ], "security": [], "responses": { "200": { "description": "Generated OpenAPI 3 contract for the deployed API binary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true, "properties": { "openapi": { "type": "string", "pattern": "^3\\.", "example": "3.0.3" }, "info": { "type": "object", "additionalProperties": true }, "paths": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Contract endpoint not found (misconfigured route).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Check API health", "description": "Returns the current developer-facing API health status. Use this endpoint for connectivity checks and include X-Correlation-ID when escalating an unexpected result.", "security": [], "responses": { "200": { "description": "API is reachable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "example": "healthy", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } }, "example": { "status": "healthy", "timestamp": "2026-08-09T00:00:00Z", "version": "0.1.22" } } } }, "503": { "description": "API is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "example": "unavailable", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "timestamp": { "type": "string", "format": "date-time" } } }, "example": { "status": "unavailable", "timestamp": "2026-08-09T00:00:00Z" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "endpoint-specific", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/uploads": { "post": { "operationId": "initiateObjectUpload", "summary": "Initiate a presigned object upload", "description": "Returns a short-lived presigned PUT URL the caller uses to upload a binary\npayload directly to object storage (S3-compatible), bypassing the API for\nthe bytes themselves. The returned `upload_id` is then referenced in a\ndownstream ingest call (e.g. POST /v1/catalogues/{catalogue-ref}/bulk-write).\n\nThe response is a bare `{data: ...}` envelope (no `status` field).\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "responses": { "200": { "description": "Presigned upload initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/objectUploadInitiateResponse" }, "example": { "data": { "upload_id": "310cf32d-9203-5f14-9574-38c755ef42fa", "put_url": "https://api.afr-dev.axiom.express/v1/objects/310cf32d-9203-5f14-9574-38c755ef42fa?X-Amz-Signature=...", "object_uri": "managed-object://redacted", "expires_at": "2026-06-02T13:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "presigned-upload-initiation", "api_byte_transport": "metadata-only", "numeric_byte_limit": "not-published", "commitment_status": "unavailable", "enforcement_owner": "object-store-presigned-put", "replacement_decision": "Publish an object-size commitment only when the presigned PUT flow exposes a runtime-enforced content-length-range condition or equivalent object-store policy proof." }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJobStatus", "summary": "Get async job status", "description": "Returns the current state of an async job. Terminal states\n(`succeeded`, `failed`, `dead_letter`) are cacheable; non-terminal states\n(`queued`, `running`) are returned with no-store.\n\nThe response is a bare `{data: ...}` envelope (no `status` field).\n", "tags": [ "Contract" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "UUID of the async job to poll.", "example": "310cf32d-9203-5f14-9574-38c755ef42fa" } ], "responses": { "200": { "description": "Job status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/jobStatusResponse" }, "example": { "data": { "id": "310cf32d-9203-5f14-9574-38c755ef42fa", "kind": "catalogue.ingest", "state": "running", "submitted_at": "2026-06-02T12:00:00Z", "attempt": 1, "max_attempts": 3, "progress": { "completed_units": 1200, "total_units": 5000, "message": "ingesting entries" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/replacements": { "post": { "operationId": "initiateReplacement", "summary": "Initiate a policy replacement", "description": "Starts a replacement workflow that supersedes one or more existing policies\nwith a replacement policy. Returns the initial workflow state including the\nallowed transitions from the starting step.\n", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementInitiateRequest" }, "example": { "policy_id": "pol_01j1234567890abcdefghijk", "existing_policy_ids": [ "pol_01j9876543210abcdefghijk" ], "jurisdiction_code": "za", "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Customer requested upgrade to comprehensive cover", "occurred_at": "2026-06-02T12:00:00Z" } } } }, "responses": { "201": { "description": "Replacement workflow initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}": { "get": { "operationId": "getReplacement", "summary": "Get a replacement workflow", "description": "Fetch the current state of a replacement workflow by id.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "responses": { "200": { "description": "Replacement workflow state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/advance": { "post": { "operationId": "advanceReplacement", "summary": "Advance a replacement workflow", "description": "Advances the workflow to the next step, supplying the evidence payload\nrequired by the current step. Optimistic-concurrency via `version`.\n", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementAdvanceRequest" }, "example": { "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Replacement disclosure acknowledged", "occurred_at": "2026-06-02T12:05:00Z", "evidence_payload": { "disclosure_acknowledged": true }, "version": 1 } } } }, "responses": { "200": { "description": "Replacement advanced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/cancel": { "post": { "operationId": "cancelReplacement", "summary": "Cancel a replacement workflow", "description": "Cancels an in-flight replacement workflow. Optimistic-concurrency via `version`.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementCancelRequest" }, "example": { "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Customer withdrew request", "occurred_at": "2026-06-02T12:10:00Z", "version": 1 } } } }, "responses": { "200": { "description": "Replacement cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/evidence": { "get": { "operationId": "getReplacementEvidence", "summary": "Get replacement evidence", "description": "Returns the evidence collected per step for a replacement workflow.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "responses": { "200": { "description": "Replacement evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementEvidenceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/archive/objects": { "post": { "operationId": "ingestArchiveObject", "summary": "Upload an object to the archive", "description": "Multipart upload of a single binary payload into the Axiom archive.\nThe `file` part is required; `original_filename`, `mime_type`, and `source`\nare optional. When omitted, the API derives them from the file header,\nContent-Type, and literal source `\"api\"`.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The binary payload to archive." }, "original_filename": { "type": "string", "description": "Original filename; falls back to the upload part's filename." }, "mime_type": { "type": "string", "description": "MIME type; falls back to the part Content-Type or application/octet-stream." }, "source": { "type": "string", "description": "Provenance tag (default \"api\")." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Object archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveIngestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List events", "description": "Retrieve a cursor-paginated list of events (real-world incidents) for the\noperating tenant (tenant-isolated). Sorted by occurred_at\ndescending (most recent incident first), tie-broken by id for stable\npagination. Filter by event_type, status, and/or policy_id (query params);\nevent_type and status are free-form domain strings, so a non-matching\nvalue simply matches nothing.\n\nLegacy limit/offset pagination is rejected; clients must use page[size]\nand page[after].\n", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to events of this type" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to events in this lifecycle status" }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Filter to events reported against this policy" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of events to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" } ], "responses": { "200": { "description": "Events retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" }, "examples": { "events_list": { "summary": "Events for a tenant", "value": { "data": [ { "id": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "event_type": "accident", "occurred_at": "2026-03-08T16:00:00Z", "reported_at": "2026-03-08T16:02:00Z", "status": "validated", "severity": "minor", "policy_id": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1", "estimated_loss": 5000000, "currency": "zar", "requires_notification": false } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "event_type", "status", "policy_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/events/{id}": { "get": { "operationId": "getEvent", "summary": "Get an event by ID", "description": "Retrieve a single event by its id, scoped to the operating tenant\n(tenant-isolated). A cross-tenant id returns 404.\n", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Event id (wire form)" } ], "responses": { "200": { "description": "Event retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/events/{event_id}/documents": { "post": { "operationId": "uploadEventDocuments", "summary": "Upload documents to an event", "description": "Multipart upload of one or more files attached to an existing event.\nEvery file part in the form is ingested into the archive and linked to\nthe event.\n", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Event id (typed-prefix wire form)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "One or more file parts (any field names).", "additionalProperties": { "type": "string", "format": "binary" } } } } }, "responses": { "201": { "description": "Documents ingested and linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadEventDocumentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events/report": { "post": { "description": "Record a tenant-reported event with supporting documents. An event is the Axiom assertion primitive \u2014 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.", "operationId": "reportEventWithDocuments", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventReportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReportResponse" } } }, "description": "Event reported with documents." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [ "events:report" ] } ], "summary": "Report Event", "tags": [ "Event", "Evidence" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events:report" ], "required_permissions": [ "events:report" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events/{id}/proration-adjustments": { "post": { "description": "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.", "operationId": "applyProrationAdjustment", "parameters": [ { "description": "Path parameter `id`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentResponse" } } }, "description": "Proration adjustment decision applied." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [ "events:proration-adjust" ] } ], "summary": "Apply Proration Adjustment", "tags": [ "Event", "Premium", "Policy", "Benefit" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events:proration-adjust" ], "required_permissions": [ "events:proration-adjust" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/role-types": { "get": { "operationId": "listRoleTypes", "summary": "List available party role types", "description": "Returns the catalogue of party role types available to the tenant. This\nis the permissible role_type vocabulary and metadata, not the set of role\ntypes currently in use. Use `GET /v1/parties/role-types/usage` for active\nassignment counts.\n\nRuntime source: the tenant `catalogue.role_types` table. Bootstrap\nregistry metadata may enrich known seed codes, but the tenant catalogue is\nthe authority for which role_type values are available.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "responses": { "200": { "description": "Available party role types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTypeListResponse" }, "example": { "data": [ { "code": "policyholder", "display_name": "Policyholder", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true }, { "code": "beneficiary", "display_name": "Beneficiary", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true } ], "meta": { "total": 18, "limit": 18, "offset": 0 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/role-types/usage": { "get": { "operationId": "listRoleTypeUsage", "summary": "Role-type usage counts", "description": "Returns each role type that has at least one active (non-revoked)\nassignment for the tenant, with the count of holders. Role types in the\nregistry with zero holders are not returned \u2014 pair with\n`GET /v1/parties/role-types` to render \"available but unused\" rows.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "responses": { "200": { "description": "Role-type usage counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTypeUsageListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties": { "post": { "description": "Register a party identity record that may later carry roles. A party is the foundational Axiom primitive anchoring all relationships \u2014 to covers, policies, premiums, and events. This contract creates the identity record; role assignment is a separate operation.", "operationId": "createParty", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } }, "description": "Party created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request, including invalid lifecycle transition shape such as status=merged without merged_into_party_id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Server Error" } }, "security": [ { "BearerAuth": [ "parties:register" ] } ], "summary": "Register Party", "tags": [ "Party" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "parties:register" ], "required_permissions": [ "parties:register" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listParties", "summary": "List parties", "description": "Retrieve a paginated list of parties for the tenant.\nResults are sorted by created_at descending. Sort order is not configurable.\n\nSupports cursor-based pagination via page[size] and page[after] query parameters.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of parties to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page." }, { "name": "source_system", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "description": "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." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Exact external identifier filter. Must be supplied together with source_system so bare external_id cannot create ambiguous identity resolution." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3 }, "description": "Free-text search term for Party lookup. The runtime rejects search terms shorter than three characters." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tenant `catalogue.role_types` code filter for parties currently holding the role." } ], "responses": { "200": { "description": "Parties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "source_system", "external_id", "q", "role" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}": { "get": { "operationId": "getParty", "summary": "Get a party by ID", "description": "Retrieve a single party by its unique identifier, including any assigned roles.\nWhen as_of or recorded_at is supplied, the response replays the party from\nthe immutable party history substrate using effective time and recorded time\nas-was semantics.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "RFC3339 effective-time timestamp for party history replay. Defaults to current effective time." }, { "name": "recorded_at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "RFC3339 recorded-time timestamp for as-was party history replay. Defaults to the latest recorded version." } ], "responses": { "200": { "description": "Party retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "recorded_at" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateParty", "summary": "Update a party", "description": "Update an existing party's attributes and/or status.\nAttribute updates are merged with existing attributes (partial update semantics).\n\nSide effects: updates the party record; emits an audit entry recording the change.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartyRequest" } } } }, "responses": { "200": { "description": "Party updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/roles": { "get": { "operationId": "getPartyRoles", "summary": "Get roles assigned to a party", "description": "Retrieve all role assignments for a party across policies, claims, and other entities.\nEach role includes the context (entity type and ID) it is scoped to.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Party roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "addPartyRole", "summary": "Assign a role to a party", "description": "Assign a new role to a party, scoped to a specific entity (e.g. a policy,\nclaim, product, organization, policy item, or PartyGroup). For sponsor\nrole assignments on a group context, the sponsor remains the Party role\nassignee and the PartyGroup is identified by entity_type=group/entity_id.\nOnly one active sponsor is allowed per tenant/group context; duplicate\nactive sponsor attempts return SPONSOR_CARDINALITY_VIOLATED (HTTP 409).\n\nA party can hold multiple roles simultaneously, and the same party can hold\ndifferent roles on different entities.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_type", "entity_type", "entity_id", "assigned_by" ], "properties": { "role_type": { "type": "string", "description": "Tenant `catalogue.role_types` code to assign. The server validates the code against the tenant catalogue, not a closed OpenAPI enum." }, "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item", "group" ], "description": "The type of entity this role is scoped to" }, "entity_id": { "type": "string", "format": "typed-prefix-id", "description": "The identifier of the entity this role is scoped to", "x-axiom-identifier-shape": "typed-prefix" }, "assigned_by": { "type": "string", "description": "Identifier of the user or service assigning this role" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional attributes for the role assignment" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Role assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/contacts": { "get": { "operationId": "listPartyContacts", "summary": "List contacts for a party", "description": "Retrieve all contact records associated with a party. A party may have multiple\ncontacts (e.g. personal email, work email, mobile, landline).\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Contacts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyContact", "summary": "Add a contact to a party", "description": "Create a new contact record for a party. Each contact includes an email address,\nphone number, and/or preferred contact method. Parties in opted_out status reject\nnew contact capture with a 409 while historical contact reads remain available.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInfo" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/contacts/{contactId}": { "put": { "operationId": "updatePartyContact", "summary": "Update a party contact", "description": "Update an existing contact record for a party.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique contact identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInfo" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deletePartyContact", "summary": "Delete a party contact", "description": "Remove a contact record from a party.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique contact identifier" } ], "responses": { "204": { "description": "Contact deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/identities": { "get": { "operationId": "listPartyIdentities", "summary": "List identity documents for a party", "description": "Retrieve all identity documents associated with a party (e.g. passport, national ID,\ntax number, company registration). Each identity has a verification status.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Identities retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyIdentity", "summary": "Add an identity document to a party", "description": "Register a new identity document for a party. The identity is created in\n\"unverified\" status and must be verified separately via the verify endpoint.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "identity_type", "identity_value" ], "properties": { "identity_type": { "type": "string", "description": "Type of identity document" }, "identity_value": { "type": "string", "description": "The identity document number or value" }, "issuing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code of issuing authority" }, "expiry_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiry date of the identity document" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Identity document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/identities/{identityId}/verify": { "post": { "operationId": "verifyPartyIdentity", "summary": "Verify a party identity document", "description": "Mark an identity document as verified. This records the verification timestamp\nand transitions the identity status from \"unverified\" to \"verified\".\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique identity document identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_method": { "type": "string", "description": "Method used for verification (e.g. manual, electronic, biometric)" }, "verified_by": { "type": "string", "description": "Identifier of the user or service performing verification" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes about the verification" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Identity verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/relationships": { "get": { "operationId": "getPartyRelationships", "summary": "List relationships for a party", "description": "Retrieve relationships for a party. The view parameter selects the response shape:\n\n- list (default): returns all active relationships as a flat array of relationship objects.\n- distribution_chain: traverses the distribution chain from this party, returning\n participants and an explanation tree (governed contract).\n\nAn unrecognised view value returns 400 INVALID_REQUEST under the governed contract.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "list", "distribution_chain" ], "default": "list" }, "description": "Response view type. Unknown values return 400 INVALID_REQUEST under the governed contract." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time filter for relationships (ISO 8601). Defaults to current time." }, { "name": "relationship_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tenant `catalogue.relationship_types` code filter." }, { "name": "max_depth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 16 }, "description": "Maximum traversal depth for view=distribution_chain (1-16). Ignored for view=list." } ], "responses": { "200": { "description": "Relationships retrieved successfully. Shape depends on the view parameter.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PartyRelationshipListResponse" }, { "$ref": "#/components/schemas/PartyDistributionChainResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "relationship_type", "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyRelationship", "summary": "Create a relationship between two parties", "description": "Creates a directed relationship from the identified party (from_party_id) to another\nparty (to_party_id). On success, returns 201 Created with the new relationship resource.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to_party_id", "relationship_type" ], "properties": { "to_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Target party for the relationship", "x-axiom-identifier-shape": "typed-prefix" }, "relationship_type": { "type": "string", "description": "Tenant `catalogue.relationship_types` code. The server validates the code against the tenant catalogue, not a closed OpenAPI enum." }, "effective_from": { "type": "string", "format": "date-time", "nullable": true, "description": "Relationship valid-from timestamp (ISO 8601). Defaults to now." }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Relationship expiry timestamp. Null means open-ended." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional key-value metadata for the relationship" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Relationship created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRelationshipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/relationships/{relId}": { "delete": { "operationId": "deletePartyRelationship", "summary": "Delete (deactivate) a party relationship", "description": "Temporally deactivates a relationship by setting its effective_to to now.\nIdempotent \u2014 deactivating an already inactive relationship returns 204.\n\nBody `{\"reason\": \"...\"}` is required (non-blank after trim) per .\nBlank reason returns 400 PARTY_DEACTIVATION_REASON_REQUIRED.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "relId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique relationship identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Non-blank rationale for the deactivation. Recorded on the audit record under the governed contract." } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Relationship deleted (deactivated) successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/party-groups": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "pty_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listGroupsForParty", "summary": "List party groups containing this party", "description": "Inverse projection \u2014 returns the groups the given party is a member\nof as of `as_of`. Distinct from `/v1/parties/:id/groups` which\nreturns Policy Group (governed contract) memberships.\n", "tags": [ "Party", "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Groups the party belongs to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/groups": { "get": { "operationId": "listPartyPolicyGroups", "summary": "List the policy-driven groups a party belongs to", "description": "Returns the **transitive** policy-group membership view for a party: the\ngroups the party belongs to by virtue of a policy binding, each annotated\nwith the `via_policy_id` that confers the membership. This is distinct\nfrom `/v1/parties/{id}/party-groups` (first-class, directly-assigned\nparty-group memberships) \u2014 here membership is derived from policy\nparticipation, not a direct grouping assignment.\n\nPoint-in-time: pass `as_of` (RFC3339) to resolve membership as it stood at\nthat instant; defaults to now.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Resolve membership as-of this instant (RFC3339). Defaults to now." } ], "responses": { "200": { "description": "Policy-driven group memberships for the party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyPolicyGroupListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/payments": { "get": { "operationId": "getPartyPayments", "summary": "List payments for a party", "description": "Retrieves a paginated list of payments associated with a specific party.\nReturns only payments explicitly linked to the party via `party_id`.\nPayments without party linkage (null `party_id`) are excluded.\n\nResults are sorted by created_at descending with id as a stable\ntie-breaker. Use `page[size]` and `page[after]` for pagination. Legacy\n`limit` and `offset` query parameters are rejected.\n", "tags": [ "Party", "Payment" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of payments to return" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Party payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyPaymentListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/audit": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyAudit", "summary": "Chronological audit feed for a party", "description": "Returns the per-party audit feed in chronological order\n(`performed_at DESC`). Each event carries governed contract actor attribution\n(`actor_id` / `actor_type` / `actor_original_id`) regardless of\nwriter path. The reader merges persistence-managed records and application writes\nso the consumer sees a single shape.\n\nExplanation enrichment fields (`decision_id`, `rule_versions`,\n`inputs`) are populated for rules-evaluation records only and\nempty otherwise (preview placeholder).\n\nUse `page[size]` and `page[after]` for cursor pagination. Legacy\n`limit` and `offset` query parameters are rejected by the runtime.\n", "tags": [ "Party" ], "parameters": [ { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of audit entries to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Audit feed for this party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyAuditListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/audit": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupAudit", "summary": "Chronological audit feed for a party group", "description": "Returns the per-group audit feed in chronological order\n(`performed_at DESC`). party_groups + party_group_memberships have\nno persistence-managed records, so every row is generated by the\napplication's `NewAuditRecord` path with a `party.group_*`\noperation code.\n\nResponse shape mirrors `/v1/parties/{id}/audit` \u2014 see that endpoint\nfor the full `AuditEntry` field list.\n\nUse `page[size]` and `page[after]` for cursor pagination. Legacy\n`limit` and `offset` query parameters are rejected by the runtime.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of audit entries to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Audit feed for this party group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupAuditListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues": { "get": { "operationId": "listCatalogues", "summary": "List catalogues", "description": "Returns catalogue parents visible to the caller's tenant. Tenant-scoped\ncatalogues from other tenants are filtered out (not 404'd individually).\nTenant isolation is enforced at the persistence layer by tenant-isolated.\n\nOptional `slug` filter for exact slug match; `include_discarded` exposes\nsoft-discarded parents for audit / recovery purposes (defaults false).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "slug", "in": "query", "required": false, "description": "Exact catalogue slug filter (e.g. `icd-10-za`).", "schema": { "type": "string" } }, { "name": "include_discarded", "in": "query", "required": false, "description": "When true, includes soft-discarded catalogue parents in the result.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of catalogue parents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalogueListResponse" }, "example": { "data": [ { "id": "cc347178-b31f-571d-8ed1-b2513427d36f", "slug": "icd-10-za", "name": "ICD-10-ZA", "source": "WHO/DoH-ZA", "refresh_frequency": "annual", "substrate": "bi-temporal", "has_descriptor": false, "created_at": "2026-01-15T08:00:00Z", "updated_at": "2026-01-15T08:00:00Z" } ], "meta": { "limit": 0, "offset": 0, "count": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "slug", "include_discarded" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}": { "get": { "operationId": "getCatalogue", "summary": "Get catalogue", "description": "Fetch a single catalogue parent by its slug identifier. Returns\ndiscarded parents too (audit / as-was reconstruction); the\n`discarded_at`, `discarded_by`, and `discard_reason` fields are\npopulated when set.\n\nTenant isolation enforced at persistence layer by tenant-isolated. Cross-tenant\nslugs yield 404, not 403.\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRefPath" } ], "responses": { "200": { "description": "Catalogue parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalogueSingleResponse" }, "example": { "data": { "id": "cc347178-b31f-571d-8ed1-b2513427d36f", "slug": "icd-10-za", "name": "ICD-10-ZA", "source": "WHO/DoH-ZA", "refresh_frequency": "annual", "substrate": "bi-temporal", "has_descriptor": false, "created_at": "2026-01-15T08:00:00Z", "updated_at": "2026-01-15T08:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}/entries": { "get": { "operationId": "listCatalogueEntries", "summary": "List bi-temporal entries", "description": "Returns bi-temporal catalogue entries for the given catalogue parent,\nfiltered by the two-axis as-was window (`as_of` / `recorded_at`).\nTenant isolation enforced at the persistence layer by tenant-isolated.\n\nOptional filters:\n- `logical_entry_id` \u2014 return all versions of a single logical entry UUID.\n- `code` \u2014 exact code match.\n- `q` \u2014 keyword search on description.\n- `order_by=attr.` \u2014 sort by a descriptor-declared attribute field\n (contract rule; fails 400 DESCRIPTOR_FIELD_NOT_SORTABLE when the field is not\n declared in the catalogue descriptor's `roles.sort.fields`).\n- `dir=asc|desc` \u2014 sort direction (default `asc`).\n- `attr.=` \u2014 JSONB-containment filter on any attribute field\n (contract rule; when the catalogue descriptor declares `roles.search.fields`,\n only declared fields are accepted; undeclared \u2192 400 DESCRIPTOR_FIELD_NOT_SEARCHABLE).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRefPath" }, { "name": "as_of", "in": "query", "required": false, "description": "Real-world validity axis instant (RFC 3339). When provided, only\nentries whose `valid_from <= as_of < valid_to` (or `valid_to IS NULL`)\nare returned.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "recorded_at", "in": "query", "required": false, "description": "Physical-anchor axis instant (RFC 3339). When provided, only\nentries whose `recorded_from <= recorded_at` are returned, enabling\nas-was reconstruction at a prior recording moment.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "logical_entry_id", "in": "query", "required": false, "description": "UUID of the logical entry; returns all bi-temporal versions for that entry.", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "code", "in": "query", "required": false, "description": "Exact code match filter.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Keyword search on the entry description field.", "schema": { "type": "string" } }, { "name": "order_by", "in": "query", "required": false, "description": "Attribute sort field in the form `attr.`. Only fields declared in\nthe catalogue descriptor `roles.sort.fields` are accepted (contract rule allow-list).\n", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction. One of `asc` or `desc`. Defaults to `asc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Bi-temporal entries list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/biTemporalEntryListResponse" }, "example": { "entries": [ { "id": "cae_01j1234567890abcdefghijk", "logical_entry_id": "310cf32d-9203-5f14-9574-38c755ef42fa", "catalogue_id": "cat_01j1234567890abcdefghijk", "code": "J18.9", "description": "Pneumonia, unspecified organism", "status": "active", "valid_from": "2026-01-01T00:00:00Z", "recorded_from": "2026-01-15T08:00:00Z", "created_at": "2026-01-15T08:00:00Z" } ], "count": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "recorded_at", "logical_entry_id", "code", "q" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}/relationships/batch": { "post": { "operationId": "createCatalogueRelationshipBatch", "summary": "Atomically create N relationships in one transaction", "description": "Atomic batch create under the governed contract. Either every row in the\n`relationships` array is persisted, or none are. The path\n:catalogue-ref scopes the batch \u2014 every row's source_catalogue MUST\nequal the path. Unlike the single-create endpoint, source fields are\nNOT defaulted from the path; each row must specify them explicitly.\nMaximum batch size is 10000 (BATCH_SIZE_EXCEEDED 400 above that).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRelationshipRefPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "relationships" ], "properties": { "relationships": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/CatalogueRelationshipBody" } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "All relationships created atomically.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "relationships", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogueRelationship" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups": { "get": { "operationId": "listPartyGroups", "summary": "List party groups", "description": "Returns party groups for the tenant with cursor pagination. Results are\nordered by created_at descending with id as a stable tiebreaker. Supports\na free-text search via `q` (3-character minimum under the governed contract).\n", "tags": [ "Party Group" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of party groups to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." }, { "name": "q", "in": "query", "description": "Search across display_name, id, external_id (min 3 chars, governed contract)", "schema": { "type": "string", "minLength": 3 } } ], "responses": { "200": { "description": "Party group list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "q" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyGroup", "summary": "Create a party group", "description": "Creates a static or dynamic party group. For dynamic groups,\n`membership_rule_id` is required and must reference a rule of type\n`party_grouping` in the shared rules catalog (fail-loud; 400 on\ninvalid reference). Idempotent via standard Idempotency-Key header.\n", "tags": [ "Party Group" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartyGroupRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "getPartyGroup", "summary": "Get a party group with its active members", "description": "Returns the group and its active memberships as of `as_of` (defaults\nto now). Members include both party-type and group-type (developer preview\npolymorphic DAG) \u2014 callers must discriminate on `member_type`.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Group + members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updatePartyGroup", "summary": "Update display_name / description / status", "description": "Partial update \u2014 only supplied fields are changed. Soft-delete is\nachieved via setting status to `inactive` here OR calling DELETE.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartyGroupRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deletePartyGroup", "summary": "Soft delete (status \u2192 inactive)", "description": "Soft-delete \u2014 flips status to `inactive`. The group row and its\nmemberships are preserved for audit under the governed contract. There is no hard\ndelete.\n", "tags": [ "Party Group" ], "responses": { "204": { "description": "Deleted (soft)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/members": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "post": { "operationId": "addPartyGroupMember", "summary": "Add a party or group as a member", "description": "Body must supply exactly one of `party_id` or `group_id`. Neither or\nboth \u2192 400. Cycle detection happens at read time (bounded traversal, governed contract) \u2014 writes do not block cyclic membership.\nIdempotent on (group, member_type, member_id) when a membership is\nalready open.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPartyGroupMemberRequest" } } } }, "responses": { "201": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupMembershipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/members/{partyId}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "partyId", "in": "path", "required": true, "description": "Member id. The path parameter is named `partyId` for legacy reasons;\nthe endpoint accepts both party-member-ids and group-member-ids\n(developer preview \u2014 any member_id regardless of type).\n", "schema": { "type": "string", "format": "typed-prefix-id", "example": "pty_01arz3ndektsv4rrffq69g5fav" } } ], "delete": { "operationId": "removePartyGroupMember", "summary": "Close a member's open window (sets valid_to = now)", "description": "Idempotent \u2014 if no open membership exists, returns 204 without error.\nDoes not hard-delete the membership row; the closed window is\npreserved for audit (governed contract).\n", "tags": [ "Party Group" ], "responses": { "204": { "description": "Membership closed (or no-op if already closed)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/flat-members": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupFlatMembers", "summary": "List all party members reachable via recursive expansion", "description": "Recursively walks the membership DAG and returns every party that is\nreachable \u2014 de-duplicated by party_id. Uses bounded traversal with a\ncycle guard (governed contract): diamonds are de-duped, cycles are\nshort-circuited.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "description": "BFS depth cap [1, 16]. Server returns 400 for out-of-range. 0 or omitted \u2192 default (4).", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "De-duplicated flat member list with paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupFlatMemberListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/ancestors": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupAncestors", "summary": "List groups that transitively contain this group", "description": "BFS upward through the membership DAG up to `max_depth`.", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "Ancestor groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/descendants": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupDescendants", "summary": "List groups transitively contained by this group", "description": "BFS downward through the membership DAG up to `max_depth`.", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "Descendant groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/evaluate": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "post": { "operationId": "evaluatePartyGroupMembership", "summary": "Dry-run evaluate a party against a dynamic group's rule", "description": "Read-only evaluation \u2014 calls the membership-rule evaluator and\nreturns `is_member` plus an explanation summary. Does NOT persist\nmembership. Only valid for `group_type = dynamic`; static groups\nreturn 400. Classification: `intentional_exception` in the\npost-route manifest (POST that doesn't mutate).\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatePartyGroupRequest" } } } }, "responses": { "200": { "description": "Evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/roles": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupRoles", "summary": "List roles held directly by this group", "description": "Returns roles where this group is the assignee (`assignee_type =\ngroup`). under the governed contract there is NO automatic inheritance \u2014\nthese roles do not flow to member parties.\n", "tags": [ "Party Group" ], "responses": { "200": { "description": "Roles held by the group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupRoleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "assignPartyGroupRole", "summary": "Assign a role to the group", "description": "Assigns a role with the group as assignee. Idempotent via\nIdempotency-Key.\n\nFor role_type=accepted_provider_network:\n- Assignee group must have composition_type=provider_network \u2192 422 INVALID_ASSIGNMENT otherwise.\n- Context entity_type must be product \u2192 context entity_id must reference an\n existing product in the tenant \u2192 404 PRODUCT_CONTEXT_NOT_FOUND if missing.\n- Overlapping active windows on the same (group, role_type, product) tuple\n return 409 NETWORK_ROLE_ALREADY_ACTIVE.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignGroupRoleRequest" } } } }, "responses": { "201": { "description": "Role assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupRoleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/roles/{roleId}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav" } } ], "delete": { "operationId": "revokePartyGroupRole", "summary": "Revoke a role held by the group", "description": "Closes the role assignment with an optional reason supplied as a\nJSON body `{reason: \"...\"}`.\n", "tags": [ "Party Group" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Role revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products": { "post": { "operationId": "createProduct", "summary": "Create a new insurance product", "description": "Create a product definition in the catalogue. Products define the coverage template\nfrom which policies are issued. A product includes coverage sections (covers),\nconfigurable terms, pricing rules, and commission structures.\n\nProducts are created in \"draft\" status and must be explicitly activated before\npolicies can be issued against them.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" }, "examples": { "motor_tpl": { "summary": "Motor third-party liability product (UK)", "value": { "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": { "base_premium": 120000, "region": "UK", "regulatory_class": "compulsory", "minimum_age": 17 }, "covers": [ { "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": 1000000, "deductible": 0 }, { "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "description": "Covers liability for damage to third-party property", "type": "basic", "sum_insured": 250000, "deductible": 500 } ], "terms": [ { "code": "POLICY-DURATION", "name": "Policy Duration", "data_type": "integer", "required": true } ] } }, "health_comprehensive": { "summary": "Comprehensive health cover", "value": { "product_code": "HEALTH-COMP-2026", "name": "Comprehensive Health Cover", "type": "health", "description": "Comprehensive health plan covering inpatient, outpatient, dental, and optical care", "currency": "USD", "attributes": { "base_premium": 250000, "scheme_type": "open", "regulatory_registration": "HIC-2026-001" }, "covers": [ { "code": "INPATIENT", "name": "Inpatient Hospital Cover", "description": "Covers hospitalisation, surgery, and ICU stays", "type": "basic", "sum_insured": 5000000, "deductible": 0 }, { "code": "DENTAL", "name": "Dental Cover", "description": "Covers dental consultations, fillings, and extractions", "type": "optional", "sum_insured": 25000, "deductible": 500 } ], "terms": [ { "code": "WAITING-PERIOD-DAYS", "name": "Waiting Period", "data_type": "integer", "required": true } ] } }, "property_commercial": { "summary": "Commercial property insurance (Brazil)", "value": { "product_code": "PROP-COMM-2026", "name": "Seguro Empresarial", "type": "property", "description": "Commercial property insurance covering fire, theft, natural disasters, and business interruption", "currency": "BRL", "attributes": { "base_premium": 500000, "market": "LATAM", "susep_code": "0114" }, "covers": [ { "code": "FIRE", "name": "Fire Cover", "description": "Covers damage caused by fire", "type": "basic", "sum_insured": 10000000, "deductible": 5000 } ], "terms": [ { "code": "CONSTRUCTION-TYPE", "name": "Construction Type", "data_type": "string", "required": true } ] } } } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "motor_created": { "summary": "Motor product created in draft status", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "draft", "description": "Mandatory third-party liability cover for motor vehicles registered in the United Kingdom", "currency": "GBP", "attributes": { "base_premium": 120000, "region": "UK", "regulatory_class": "compulsory", "minimum_age": 17 }, "covers": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "TPL-BODILY", "name": "Third-Party Bodily Injury", "type": "basic", "sum_insured": 1000000, "deductible": 0, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "type": "basic", "sum_insured": 250000, "deductible": 500, "status": "active" } ], "terms": [ { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "POLICY-DURATION", "name": "Policy Duration", "data_type": "integer", "required": true } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Product created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listProducts", "summary": "List products", "description": "Retrieve a paginated list of products in the tenant's catalogue.\nResults are sorted by recorded_at descending with a stable cursor\ntiebreaker. Sort order is not configurable.\n\nBoth draft and active products are returned. Use the status field to filter\nif needed (client-side filtering).\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of products to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque product cursor from the previous response meta.next_cursor" } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" }, "examples": { "product_list": { "summary": "Mixed product types", "value": { "data": [ { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "active", "description": "Mandatory third-party liability cover for motor vehicles", "currency": "GBP", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, { "id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "product_code": "HEALTH-COMP-2026", "name": "Comprehensive Health Cover", "type": "health", "status": "active", "description": "Comprehensive health plan covering inpatient, outpatient, dental, and optical care", "currency": "USD", "created_at": "2026-03-11T14:00:00Z", "updated_at": "2026-03-11T14:00:00Z" }, { "id": "542f58e3-8bbd-5c5a-9f6e-d0c506b771cd", "product_code": "LIFE-TERM-2026", "name": "Term Life Assurance", "type": "life", "status": "draft", "description": "Fixed-term life assurance with lump sum death benefit", "currency": "USD", "created_at": "2026-03-10T09:00:00Z", "updated_at": "2026-03-10T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a product by ID", "description": "Retrieve a single product with its full configuration including covers,\nterms, pricing rules, and commission structures.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "full_product": { "summary": "Fully configured liability product", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "LIAB-PROF-2026", "name": "Professional Indemnity Insurance", "type": "liability", "status": "active", "description": "Professional indemnity cover for regulated professionals including legal, accounting, and consulting firms", "currency": "EUR", "attributes": { "market": "EMEA", "eligible_professions": [ "legal", "accounting", "consulting", "engineering" ] }, "covers": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "PI-CLAIMS", "name": "Professional Negligence Claims", "type": "basic", "sum_insured": 2000000, "deductible": 5000, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "PI-DEFENCE", "name": "Legal Defence Costs", "type": "basic", "sum_insured": 500000, "deductible": 0, "status": "active" } ], "terms": [ { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "RETRO-DATE", "name": "Retroactive Date", "data_type": "date", "required": true }, { "id": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "code": "RUN-OFF-YEARS", "name": "Run-Off Period", "data_type": "integer", "required": false, "default_value": "6" } ], "pricing_rules": [ { "id": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "name": "Revenue Band Rating", "rule_type": "risk_factor", "base_rate": 0.005, "expression": "revenue_band == 'high' ? 0.008 : 0.005", "status": "active" } ], "commissions": [ { "id": "fa590161-dad2-5a57-84d1-4a71d6457a36", "role_type": "broker", "commission_type": "initial", "rate": 0.15, "calculation_basis": "gross_premium", "status": "active" } ], "created_at": "2026-02-01T10:00:00Z", "updated_at": "2026-03-01T16:00:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateProduct", "summary": "Update a product", "description": "Update an existing product's metadata, attributes, or status.\nProducts can be transitioned from \"draft\" to \"active\" status via this endpoint.\n\nUpdating an active product creates a new version. Existing policies issued under\nprevious versions are not affected.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated display name", "example": "Motor TPL \u2014 Enhanced" }, "description": { "type": "string", "description": "Updated description" }, "status": { "type": "string", "enum": [ "draft", "active" ], "description": "Updated product status" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated extensible attributes (merged with existing)" } }, "additionalProperties": false }, "examples": { "activate_product": { "summary": "Activate a draft product", "value": { "status": "active" } }, "update_metadata": { "summary": "Update product description and attributes", "value": { "description": "Enhanced motor third-party liability with increased bodily injury limits", "attributes": { "max_vehicle_age_years": 15, "minimum_age": 18 } } } } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "activated": { "summary": "Product activated", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "active", "description": "Mandatory third-party liability cover for motor vehicles", "currency": "GBP", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T10:00:00Z" }, "status": "success", "message": "Product updated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/covers": { "get": { "operationId": "getProductCovers", "summary": "Get coverage sections for a product", "description": "Retrieve all coverage sections (covers) defined for a product. Each cover\nincludes its sum insured, deductible, type (basic/optional/rider), and any\nassociated cover provision definitions and terms.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "responses": { "200": { "description": "Covers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverListResponse" }, "examples": { "motor_covers": { "summary": "Motor product coverage sections", "value": { "data": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "TPL-BODILY", "name": "Third-Party Bodily Injury", "description": "Covers liability for bodily injury to third parties", "type": "basic", "sum_insured": 1000000, "deductible": 0, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "description": "Covers liability for damage to third-party property", "type": "basic", "sum_insured": 25000000, "deductible": 50000, "status": "active" }, { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "WINDSCREEN", "name": "Windscreen Cover", "description": "Covers repair or replacement of windscreens and vehicle glass", "type": "optional", "sum_insured": 500000, "deductible": 0, "status": "active" } ], "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "addCover", "summary": "Add a coverage section (cover) to a product", "description": "CRS-3: add a cover to a draft product. The cover may carry nested\n`cover_items` (each with `terms`) and cover-level `cover_terms`, persisted\nas the full canonical cover.* row graph in one atomic transaction. Money\nboundaries are exact integer minor units with a lowercase ISO-4217 currency;\na monetary boundary missing its currency is rejected (422). Co-insurance\npanel splits (basis points) must sum to 10000bp (100%) or the request is\nrejected (422).\n", "tags": [ "Product" ], "security": [ { "BearerAuth": [ "products:write" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCoverRequest" } } } }, "responses": { "201": { "description": "Cover added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "**422 Unprocessable Entity** \u2014 the cover failed a business-rule\nvalidation (unknown cover-item kind, a money boundary missing its\ncurrency, or a co-insurance panel not summing to 10000bp).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "products:write" ], "required_permissions": [ "products:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/pricing-rules": { "get": { "operationId": "listProductPricingRules", "summary": "List product\u2194ruleset bindings (active and historical)", "description": "Returns the binding history for a product in deterministic order\n(effective_from DESC, created_at DESC, id DESC). Each item includes\n`ruleset_type` so callers can distinguish stages without re-querying.\n\nOptional `?ruleset_type=` filter narrows the response to a single\nstage. Unknown values are rejected with 400 INVALID_RULESET_TYPE\n(no silent empty-list).\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" }, { "name": "ruleset_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pipeline stage; must be in the canonical allowlist" } ], "responses": { "200": { "description": "Bindings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRulesetBindingListResponse" }, "examples": { "bindings_list": { "summary": "Active and historical bindings", "value": { "data": [ { "id": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "product_id": "prd_d4e5f6a7b8c90123def0123456789abc", "ruleset_id": "07805e66-69d7-5b42-a978-32729404b560", "ruleset_type": "premium_rating", "ruleset_version": 2, "effective_from": "2026-03-01T00:00:00Z", "created_by": "usr_abc123" }, { "id": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "product_id": "prd_d4e5f6a7b8c90123def0123456789abc", "ruleset_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "ruleset_type": "premium_rating", "ruleset_version": 1, "effective_from": "2026-01-01T00:00:00Z", "effective_to": "2026-03-01T00:00:00Z", "created_by": "usr_abc123" } ], "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "ruleset_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/activate": { "post": { "operationId": "activateProduct", "summary": "Activate a draft product", "description": "Transition a product from draft to active status. The product must have at\nleast one cover and defined terms (with explicit validation bounds) before\nactivation.\n\nThis is a status-only transition: it does NOT re-persist the product's\ncover graph, so it never collides on existing covers (unlike a full\nPUT update). Side effects: persists the status change and emits a formal\nactivation explanation tree (governed contract).\n", "tags": [ "Product" ], "security": [ { "BearerAuth": [ "products:write" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateProductRequest" } } } }, "responses": { "200": { "description": "Product activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "products:write" ], "required_permissions": [ "products:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies": { "post": { "operationId": "createPolicy", "summary": "Create a new policy", "description": "Issue a new insurance policy under an active product. The policy is created in\n\"draft\" status by default. At least one party must be assigned (typically the\npolicyholder). Draft policies are not endorsement-eligible; use\n`POST /v1/policies/bind` to create an active, endorsement-eligible policy.\n\nThe product must be in \"active\" status before policies can be issued against it.\nThe effective date must not be in the past (backdating requires special permissions).\n\nSide effects: persists the policy in draft status with assigned parties; emits an audit entry recording the creation.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" }, "examples": { "motor_policy": { "summary": "Motor third-party liability policy (UK)", "value": { "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "vehicle_year": 2023, "sum_insured": 1000000, "territory": "UK" }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "role": "policyholder" }, { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "role": "insured" } ], "created_by": "agent-user-012" } }, "health_policy": { "summary": "Health cover policy", "value": { "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "effective_date": "2026-05-01", "expiry_date": "2027-04-30", "attributes": { "plan_level": "comprehensive", "dependents": 3, "chronic_conditions": [ "diabetes_type_2" ] }, "parties": [ { "party_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "role": "policyholder" }, { "party_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "role": "dependent" }, { "party_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "role": "beneficiary" } ], "created_by": "broker-portal" } }, "life_policy": { "summary": "Term life assurance (Nigeria)", "value": { "product_id": "542f58e3-8bbd-5c5a-9f6e-d0c506b771cd", "effective_date": "2026-06-01", "expiry_date": "2046-05-31", "attributes": { "sum_assured": 50000000, "currency": "NGN", "smoker_status": "non_smoker" }, "parties": [ { "party_id": "fa633d26-7313-5660-ba5a-3bf7cef790fe", "role": "policyholder" }, { "party_id": "fa633d26-7313-5660-ba5a-3bf7cef790fe", "role": "insured" }, { "party_id": "8a939ebd-5247-5ba8-8312-2a248921d66b", "role": "beneficiary" } ], "created_by": "agent-user-042" } } } } } }, "responses": { "201": { "description": "Policy created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "motor_created": { "summary": "Motor policy created", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "draft", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "vehicle_year": 2023, "sum_insured": 1000000, "territory": "UK" }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "policyholder", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" }, { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "insured", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Policy created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listPolicies", "summary": "List policies", "description": "Retrieve a cursor-paginated list of policies for the tenant.\nResults are sorted by most-recently-recorded first. Sort order is not configurable.\nLegacy `limit` and `offset` query parameters are rejected.\n\nReturns policies across all statuses (draft, issued, active, terminated).\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of policies to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only policies the party is bound to in any role\n(the party appears in `policy.parties`). Accepts the canonical typed-prefix\nparty id (`pty_\u2026`, governed contract). A malformed value returns 400. Absent =\nall policies for the tenant (current behaviour). Composes with the\nexisting operating-tenant tenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Policies retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyListResponse" }, "examples": { "policy_list": { "summary": "Policies across statuses and verticals", "value": { "data": [ { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-04-01T00:00:00Z" }, { "id": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "policy_number": "POL-2026-000143", "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "status": "terminated", "effective_date": "2026-03-01", "expiry_date": "2027-02-28", "created_at": "2026-02-28T11:00:00Z", "updated_at": "2026-03-10T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/bind": { "post": { "description": "Bind parties to covers through an active policy version. This contract is the primary policy-creation operation \u2014 it reads party and product/cover context, creates an immutable policy version, and conditionally triggers premium effects. Requires idempotency: callers must supply an idempotency key to prevent duplicate policy creation on retry.", "operationId": "bindPolicy", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBindRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBindResponse" } } }, "description": "Policy bound successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quote not found (QUOTE_NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Idempotency key reused (IDEMPOTENCY_KEY_REUSED)" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quote expired (QUOTE_EXPIRED)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Validation error (PREMIUM_DRIFT_EXCEEDED or POLICY_NOT_YET_EFFECTIVE_FOR_BIND)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Server Error" } }, "security": [ { "BearerAuth": [ "policies:bind" ] } ], "summary": "Bind Policy", "tags": [ "Policy" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "policies:bind" ], "required_permissions": [ "policies:bind" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}": { "get": { "operationId": "getPolicy", "summary": "Get a policy by ID", "description": "Retrieve a single policy with its full details including assigned parties\nand premium schedule.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "active_policy": { "summary": "Active motor policy with parties and premiums", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "sum_insured": 1000000 }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "policyholder", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" } ], "premiums": [ { "id": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "amount": 11500, "due_date": "2026-04-01", "status": "paid", "payment_method": "debit_order" }, { "id": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "amount": 11500, "due_date": "2026-05-01", "status": "pending", "payment_method": "debit_order" } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-04-01T00:00:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/versions": { "post": { "operationId": "createPolicyVersion", "summary": "Create a new policy version", "description": "Create a new version snapshot of the policy. Policy versions provide an immutable\nrecord of the policy state at each point in time, supporting \"as-was\" semantics\nrequired for claims adjudication and regulatory reporting.\n\nEach version captures the complete policy state including attributes, parties,\nand coverage details at the time of creation.\n\nSide effects: not yet implemented. Returns 501.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "effective_date" ], "properties": { "effective_date": { "type": "string", "format": "date", "description": "Date from which this version takes effect", "example": "2026-06-01" }, "reason": { "type": "string", "description": "Reason for creating a new version", "example": "Mid-term adjustment following endorsement END-001" }, "created_by": { "type": "string", "description": "Identifier of the user or service creating this version", "example": "underwriter-user-003" } }, "additionalProperties": false }, "examples": { "endorsement_version": { "summary": "Version created after endorsement", "value": { "effective_date": "2026-06-01", "reason": "Mid-term adjustment \u2014 sum insured increase from 250,000 to 300,000", "created_by": "underwriter-user-003" } }, "renewal_version": { "summary": "Version created at renewal", "value": { "effective_date": "2027-04-01", "reason": "Annual renewal \u2014 updated premium and vehicle value", "created_by": "renewal-system" } } } } } }, "responses": { "201": { "description": "Policy version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionResponse" }, "examples": { "version_created": { "summary": "New policy version", "value": { "data": { "id": "pov_4d5e6f7a8b9c0123defa234567890123", "policy_id": "pol_1a2b3c4d5e6f7890abcdef1234567890", "version_number": 2, "version_type": "endorsement", "effective_from": "2026-06-01T00:00:00Z", "effective_to": null, "change_reason": "Mid-term adjustment \u2014 sum insured increase from 250,000 to 300,000", "created_by": "underwriter-user-003", "previous_version": "pov_1a2b3c4d5e6f7890abcdef1234567890", "created_at": "2026-05-28T14:00:00Z" }, "status": "success", "message": "Policy version created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listPolicyVersions", "summary": "List policy version snapshots", "description": "Return every immutable version snapshot for the policy, ordered by\nversion_number ascending.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy versions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/issue": { "post": { "operationId": "issuePolicy", "summary": "Issue a draft policy", "description": "Transition a policy from draft to issued status. The policy must have at\nleast one party with the policyholder role assigned.\n\nSide effects: persists the status change and emits an audit entry with\noperation code policy.issue in a single transaction.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "issued_by" ], "properties": { "issued_by": { "type": "string", "description": "Identifier of the user or service issuing the policy" }, "notes": { "type": "string", "description": "Optional notes for the issue action" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Policy issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "issued": { "summary": "Draft policy issued", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "issued", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-20T10:00:00Z" }, "status": "success", "message": "Policy issued successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/activate": { "post": { "operationId": "activatePolicy", "summary": "Activate an issued policy", "description": "Transition a policy from issued to active status. The policy's effective\ndate must be in the past or present (effective_date <= now).\n\nSide effects: persists the status change and emits an audit entry with\noperation code policy.activate in a single transaction.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "activated_by" ], "properties": { "activated_by": { "type": "string", "description": "Identifier of the user or service activating the policy" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Policy activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "activated": { "summary": "Issued policy activated", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-20T10:30:00Z" }, "status": "success", "message": "Policy activated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/allocation-simulations": { "post": { "operationId": "createAllocationSimulation", "summary": "Simulate an allocation breakdown", "description": "Validates a proposed allocation breakdown without persisting it.\nAccepts only simulation_preview as trigger. Returns 422 for semantic\nvalidation failures (sum mismatch, missing rule_id, invalid inputs).\n\nEach operation in the request specifies a benefit change (add, remove,\nchange) with proposed allocation values in allocation_inputs.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Policy identifier" } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "allocation-simulations" ] }, "attributes": { "type": "object", "required": [ "trigger", "operations" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "Optional point-in-time for simulation context" }, "base_policy_version_id": { "type": "string", "format": "uuid", "description": "Optional base policy version override", "x-axiom-identifier-shape": "uuid" }, "trigger": { "type": "string", "enum": [ "simulation_preview" ] }, "operations": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "op", "benefit_id" ], "properties": { "op": { "type": "string", "enum": [ "add_benefit", "remove_benefit", "change_benefit" ] }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "allocation_inputs": { "type": "object", "description": "Proposed allocation values for validation", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Proposed allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Simulation completed successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "allocation-simulations" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "properties": { "benefit_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string" }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "simulated": { "type": "boolean" }, "calculation_version": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (wrong content type, missing fields)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "404": { "description": "Policy not found (POLICY_NOT_FOUND)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "409": { "description": "Version conflict \u2014 no resolvable base policy version (VERSION_CONFLICT)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "422": { "description": "Semantic validation failure (sum mismatch, missing rule_id, invalid trigger)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/allocation-history": { "get": { "operationId": "listPolicyAllocationHistory", "summary": "List temporal allocation history for a policy", "description": "Returns cursor-paginated temporal allocation snapshots for all premiums\nin a policy. Ordered by effective_from DESC, created_at DESC, premium_id ASC.\nUses half-open [effective_from, effective_to) temporal semantics under the governed contract.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Policy identifier" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of resources per page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for forward pagination (allocation ID)" }, { "name": "page[before]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for backward pagination (allocation ID)" } ], "responses": { "200": { "description": "Allocation history retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "policy-allocation-history-entries" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "premium_id", "benefit_id", "amount", "allocation_percentage_bps", "allocation_basis", "calculation_version", "effective_from", "trigger" ], "properties": { "premium_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (missing policy id)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]", "page[before]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/endorsements": { "post": { "operationId": "createEndorsement", "summary": "Create a policy endorsement", "description": "Submit an endorsement (mid-term adjustment) to an **active** policy. Endorsements\nrecord structured changes to the policy terms, coverage, or parties.\nThe policy must be in `active` status; endorsing a `draft` or other non-active\npolicy returns HTTP 422 with code `INVALID_STATE_TRANSITION`.\n\nEach endorsement receives a sequential number within the policy (END-001, END-002, etc.)\nand triggers the creation of a new policy version when applied.\n\nSide effects: creates a new immutable policy version and persists party-role\nchanges when `change_type=parties`. Emits an audit entry when audit is configured.\n\nCommon endorsement types:\n- amendment: Modify existing terms (e.g. change address, increase sum insured)\n- addition: Add new coverage or parties\n- deletion: Remove coverage or parties\n- correction: Fix data entry errors\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "change_type", "description", "endorsed_by" ], "properties": { "change_type": { "type": "string", "description": "Classification of the endorsement change", "enum": [ "parties", "coverages", "terms", "premium" ], "example": "coverages" }, "description": { "type": "string", "description": "Human-readable description of the changes", "example": "Increase sum insured from R250,000 to R300,000 and update insured address" }, "new_parties": { "type": "array", "items": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string" } }, "additionalProperties": false }, "description": "New parties to add (for change_type 'parties')" }, "updated_attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Structured representation of attribute changes", "example": { "sum_insured": { "from": 250000, "to": 300000 }, "address": { "from": "42 Baker Street, London", "to": "18 Regent Street, London" } } }, "endorsed_by": { "type": "string", "description": "Identifier of the user or process creating the endorsement", "example": "underwriter-user-003" }, "effective_at": { "type": "string", "format": "date-time", "description": "Effective timestamp for party endorsements (change_type=parties).\nMust not be retroactive. Required when change_type=parties.\n" }, "party_changes": { "type": "array", "description": "Party mutations for change_type=parties endorsements. Each entry\nspecifies an operation (add/revoke/replace), party_id, and role.\n", "items": { "type": "object", "required": [ "op", "party_id", "role" ], "properties": { "op": { "type": "string", "enum": [ "add", "revoke", "replace" ] }, "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "examples": { "increase_sum_insured": { "summary": "Increase motor policy sum insured", "value": { "change_type": "coverages", "description": "Increase vehicle insured value following market revaluation", "updated_attributes": { "sum_insured": { "from": 350000, "to": 420000 }, "monthly_premium": { "from": 1850, "to": 2150 } }, "endorsed_by": "underwriter-user-003" } }, "add_driver": { "summary": "Add named driver to motor policy", "value": { "change_type": "parties", "description": "Add spouse as named driver with full driving history", "new_parties": [ { "party_id": "party-jane-smith-001", "role": "insured" } ], "updated_attributes": { "named_drivers": { "added": [ { "name": "Jane Smith", "licence_number": "SMITH801010JA9AB", "years_driving": 12 } ] } }, "endorsed_by": "agent-user-012" } } } } } }, "responses": { "201": { "description": "Endorsement created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndorsementResponse" }, "examples": { "endorsement_created": { "summary": "Endorsement pending application", "value": { "data": { "id": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "policy_id": "204a5555-2273-5dfd-8bcc-09717add6538", "endorsement_number": "END-001", "type": "amendment", "description": "Increase vehicle insured value following market revaluation", "effective_date": "2026-07-01", "status": "pending", "changes": { "sum_insured": { "from": 350000, "to": 420000 }, "monthly_premium": { "from": 1850, "to": 2150 } }, "endorsed_by": "underwriter-user-003", "created_at": "2026-06-25T14:00:00Z" }, "status": "success", "message": "Endorsement created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listEndorsements", "summary": "List policy endorsements", "description": "Return the policy's endorsements, ordered by version_number ascending.\nEndorsements are stored as policy version snapshots (no separate entity);\nthis list is the policy's versions filtered to version_type == endorsement.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy endorsements retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/certificates/{party_id}": { "get": { "operationId": "getCertificate", "summary": "Get member certificate projection", "description": "Retrieve a read-only certificate of insurance for a specific member on a\ngroup policy. Resolves the effective policy version and active roles at the\n`as_of` timestamp (defaults to now). Returns the master policy_id, party_id,\nrole list, effectivity window, and pinned version_id.\n\nNo persistence side effects \u2014 this is a pure read projection.\n\nReturns 404 if the party is unknown or inactive at the given `as_of` time.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" }, { "name": "party_id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Identifier of the member party" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time for certificate resolution (defaults to now)" } ], "responses": { "200": { "description": "Certificate projection retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateResponse" }, "examples": { "member_certificate": { "summary": "Active member certificate", "value": { "data": { "policy_id": "pol_1a2b3c4d5e6f7890abcdef1234567890", "party_id": "par_a1b2c3d4e5f67890abcdef1234567890", "version_id": "pov_4d5e6f7a8b9c0123defa234567890123", "roles": [ "policyholder", "insured" ], "effective_from": "2026-04-01T00:00:00Z", "effective_to": null }, "status": "success", "message": "Certificate retrieved successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims": { "post": { "operationId": "submitClaim", "summary": "Submit a new claim", "description": "Submit an insurance claim against a policy. The claim is created in \"submitted\"\nstatus and enters the claims workflow for assessment.\n\nThe referenced policy must be active (or within its coverage period for the\nevent date). The event must fall within the policy's effective period.\n\nThe system validates coverage eligibility, checks for duplicate claims, and\ntriggers any configured automated rules (e.g. fraud scoring).\n\nSide effects: persists the claim in submitted status; initiates the claims workflow (automated triage and assessment assignment); emits an audit entry recording the submission.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitClaimRequest" }, "examples": { "motor_accident": { "summary": "Motor accident claim", "value": { "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "description": "Rear-end collision at intersection of 5th Avenue and 42nd Street, New York. Third-party vehicle damage and whiplash injury to driver.", "claimed_amount": { "amount_minor": 8500000, "currency_code": "zar" }, "event_date": "2026-03-01", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567", "third_party_involved": true }, "metadata": { "source_system": "mobile-app", "reporter_reference": "APP-2026-0042" } } }, "property_water_damage": { "summary": "Property water damage claim (UK)", "value": { "event_id": "40726a06-5c87-5675-a57a-31805ea70e14", "policy_id": "75e1ccb2-5983-5aa7-9ba3-5a6cd095bd47", "primary_party_id": "ab18f8ca-0aca-5cf3-abe4-5e99c50d684e", "description": "Burst pipe in upstairs bathroom caused extensive water damage to ground floor. Affected areas include lounge ceiling, kitchen units, and hallway flooring.", "claimed_amount": { "amount_minor": 4500000, "currency_code": "gbp" }, "event_date": "2026-02-28", "priority": "high", "attributes": { "property_address": "14 Elm Grove, Bristol, BS8 1TB", "damage_type": "water", "emergency_repairs_done": true }, "metadata": { "source_system": "broker-portal", "broker_reference": "BRK-2026-0891" } } }, "health_hospitalisation": { "summary": "Health hospitalisation claim (Nigeria)", "value": { "event_id": "75e1ccb2-5983-5aa7-9ba3-5a6cd095bd47", "policy_id": "ab18f8ca-0aca-5cf3-abe4-5e99c50d684e", "primary_party_id": "9d590f8b-2e0e-5050-9dfa-f7a1ffcb1569", "description": "Emergency appendectomy at Lagos University Teaching Hospital. Admitted via A&E, surgery performed same day, 3-night stay.", "claimed_amount": { "amount_minor": 120000000, "currency_code": "ngn" }, "event_date": "2026-03-05", "priority": "urgent", "attributes": { "hospital_name": "Lagos University Teaching Hospital", "admission_type": "emergency", "procedure_code": "47.09" }, "metadata": { "source_system": "hospital-integration", "pre_auth_reference": "PA-2026-LUTH-0088" } } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Dual-mode claim submission with documents. The `claim_data` field\ncarries a JSON object (as a string) matching SubmitClaimRequest;\nany additional file parts are ingested as archive attachments.\n", "required": [ "claim_data" ], "properties": { "claim_data": { "type": "string", "description": "JSON object (as a string) matching SubmitClaimRequest." } }, "additionalProperties": { "type": "string", "format": "binary" } } } } }, "responses": { "201": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" }, "examples": { "claim_submitted": { "summary": "Motor claim submitted", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "submitted", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-12T08:00:00Z", "total_claimed_amount": 8500000, "description": "Rear-end collision at intersection of 5th Avenue and 42nd Street", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567" }, "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Claim submitted successfully", "telemetry": { "total_ms": 42, "handler_ms": 38, "trace_id": "abc123" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listClaims", "summary": "List claims", "description": "Retrieve a cursor-paginated list of claims for the tenant.\nResults are sorted by created_at descending with id as a stable tie-breaker.\nSort order is not configurable.\n\nReturns claims across all statuses (submitted, under_review, assessed,\npartial_approval, denied, paid, closed).\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of claims to return in this page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page.\nDo not construct or modify this value.\n" }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only claims against this policy.\nAccepts the canonical typed-prefix policy id (`pol_\u2026`, governed contract).\nA malformed value returns 400. Absent = all claims for the tenant\n(current behaviour). Composes with the existing operating-tenant tenant-isolated\nscope; never widens it.\n" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only claims whose primary party is this party\n(`primary_party_id`). Accepts the canonical typed-prefix party id\n(`pty_\u2026`, governed contract). A malformed value returns 400. Absent = all claims\nfor the tenant (current behaviour). Composes with the existing\noperating-tenant tenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Claims retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimListResponse" }, "examples": { "claims_list": { "summary": "Claims across statuses", "value": { "data": [ { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "under_review", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-02T09:00:00Z", "total_claimed_amount": 8500000, "description": "Motor accident \u2014 rear-end collision", "priority": "medium", "created_at": "2026-03-02T09:00:00Z", "updated_at": "2026-03-05T14:00:00Z" }, { "id": "1622e4e4-3099-5794-a127-5c7103afaabf", "claim_number": "CLM-2026-00041", "event_id": "6e2f41e0-f63e-5a20-a76b-0c1f296d9db7", "policy_id": "3cce17f2-f5d3-586a-9b26-50ee6428c9fb", "status": "paid", "primary_party_id": "9e3927be-a1c5-5309-be43-63195769f557", "event_date": "2026-02-15T00:00:00Z", "reported_date": "2026-02-16T10:00:00Z", "total_claimed_amount": 1250000, "description": "Theft of laptop and camera equipment from vehicle", "priority": "low", "created_at": "2026-02-16T10:00:00Z", "updated_at": "2026-03-01T16:00:00Z" } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMi0xNlQxMDowMDowMFoiLCJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS1iY2RlLTIzNDU2Nzg5MDEyMyJ9" }, "status": "success", "telemetry": { "total_ms": 18, "handler_ms": 14, "trace_id": "def456" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}": { "get": { "operationId": "getClaim", "summary": "Get a claim by ID", "description": "Retrieve a single claim with its full details including claim items,\nassessments, payments, and current workflow state.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "Claim retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" }, "examples": { "assessed_claim": { "summary": "Assessed motor claim with items and assessment", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "assessed", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-02T09:00:00Z", "total_claimed_amount": 8500000, "description": "Rear-end collision at intersection", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567" }, "claim_items": [ { "id": "32798e17-3851-562c-b192-f49109f3465d", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "item_type": "vehicle_damage", "description": "Rear bumper replacement and respray", "claimed_amount": { "amount_minor": 5500000, "currency_code": "zar" }, "approved_amount": { "amount_minor": 5200000, "currency_code": "zar" }, "status": "approved", "created_at": "2026-03-02T09:00:00Z" }, { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "item_type": "medical", "description": "Physiotherapy for whiplash \u2014 6 sessions", "claimed_amount": { "amount_minor": 3000000, "currency_code": "zar" }, "approved_amount": { "amount_minor": 2800000, "currency_code": "zar" }, "status": "approved", "created_at": "2026-03-02T09:00:00Z" } ], "assessments": [ { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "assessment_type": "initial", "assessed_by": "assessor-jvd-001", "assessed_at": "2026-03-08T16:00:00Z", "status": "approved", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "notes": "Damage consistent with reported collision. Approved less R5,000 policy excess." } ], "created_at": "2026-03-02T09:00:00Z", "updated_at": "2026-03-08T16:00:00Z" }, "status": "success", "telemetry": { "total_ms": 22, "handler_ms": 18, "trace_id": "ghi789" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/assess": { "post": { "operationId": "assessClaim", "summary": "Assess a claim", "description": "Submit an assessment for a claim. Assessments record the outcome of\ninvestigation and evaluation, including approved amounts and per-item\nassessments.\n\nThe claim must be in \"under_review\" status. After assessment, the claim\ntransitions to \"assessed\" (full approval), \"partial_approval\", or \"denied\".\n\nAutomated rule evaluation results (e.g. fraud scoring) are included in the\nassessment record for audit and explainability.\n\nSide effects: returns the assessment result with the claim status transitioned (under_review to assessed, partial_approval, or denied) without persisting the changes. Emits an audit entry when audit is configured.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessClaimRequest" }, "examples": { "approve_motor": { "summary": "Approve motor claim with excess deduction", "value": { "assessed_by": "assessor-jvd-001", "assessment_notes": "Site inspection completed. Damage verified against police report and repair quotations from two panel beaters. Approved less R5,000 policy excess.", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "item_assessments": [ { "item_id": "32798e17-3851-562c-b192-f49109f3465d", "approved_amount": { "amount_minor": 5200000, "currency_code": "zar" }, "notes": "Panel beater quotation verified. Original parts specified." }, { "item_id": "047a5bdd-844c-502f-993a-b05e907ca746", "approved_amount": { "amount_minor": 2800000, "currency_code": "zar" }, "notes": "Physiotherapy approved per medical protocol for whiplash grade II" } ], "metadata": { "inspection_date": "2026-03-06", "photos_reviewed": 18 } } }, "deny_claim": { "summary": "Deny a fraudulent claim", "value": { "assessed_by": "assessor-senior-002", "assessment_notes": "Investigation revealed older damage inconsistent with reported event date. GPS data contradicts reported location. Claim denied under policy exclusion clause 7.2 (material misrepresentation).", "metadata": { "investigation_type": "fraud", "external_report_reference": "INV-2026-0033" } } } } } } }, "responses": { "200": { "description": "Claim assessed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessClaimResponse" }, "examples": { "assessment_recorded": { "summary": "Assessment with rule evaluation results", "value": { "data": { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "assessment_type": "initial", "assessed_by": "assessor-jvd-001", "assessed_at": "2026-03-08T16:00:00Z", "status": "approved", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "notes": "Damage verified against police report and repair quotations", "rule_results": [ { "rule_id": "rule-fraud-score-v2", "rule_name": "Fraud Probability Score", "outcome": "pass", "value": "0.08", "executed_at": "2026-03-08T15:58:00Z" }, { "rule_id": "rule-coverage-check-v1", "rule_name": "Coverage Eligibility Check", "outcome": "pass", "value": "true", "executed_at": "2026-03-08T15:58:01Z" } ] }, "assessment": [ { "rule_id": "rule-fraud-score-v2", "outcome": "pass" }, { "rule_id": "rule-coverage-check-v1", "outcome": "pass" } ], "status": "success", "message": "Claim assessed successfully using tenant-specific adjudication rules", "telemetry": { "total_ms": 95, "handler_ms": 88, "trace_id": "jkl012" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failure. Codes: INVALID_STATE_TRANSITION,\nINVALID_MONETARY_AMOUNT.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "Invalid state transition", "value": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Invalid State Transition", "detail": "Claim must be under_review to be assessed, current status: paid" } ] } }, "invalid_amount": { "summary": "Invalid monetary amount", "value": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "approved_amount must be a non-negative integer in cents" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/authorisations": { "post": { "operationId": "recordClaimAuthorisation", "summary": "Record a claim authorisation", "description": "Record an governed contract authorisation sub-event against a claim. The row is\nappend-only and carries the authorising actor, authorised scope, budget,\ngoverning-version binding, optional compliance state, decision date, and\nexplanation-node reference.\n\nClaim payments may cite the returned authorisation id. When they do, the\npayment path runs the authorisation compliance gate before disbursement.\n\nSide effects: persists an `authorisation_transitions` row under the\ntenant context and returns the recorded authorisation.\n", "tags": [ "Claim" ], "security": [ { "BearerAuth": [ "claims:authorise" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationRequest" }, "examples": { "medical_pre_auth": { "summary": "Medical service authorisation", "value": { "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "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" } } } } } }, "responses": { "201": { "description": "Claim authorisation recorded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationResponse" }, "examples": { "recorded": { "summary": "Recorded authorisation", "value": { "data": { "id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "logical_authorisation_id": "a1699eac-cf08-52d7-be4d-242049b373f5", "entity_type": "claim", "entity_id": "07805e66-69d7-5b42-a978-32729404b560", "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "budget_minor": 250000, "budget_currency_code": "zar", "decision_date": "2026-07-06T10:00:00Z", "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346", "valid_from": "2026-07-06T10:00:00Z", "asserted_from": "2026-07-06T10:00:00Z" }, "status": "success", "message": "Claim authorisation recorded successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "claims:authorise" ], "required_permissions": [ "claims:authorise" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/pay": { "post": { "operationId": "payClaim", "summary": "Process a claim payment", "description": "Initiate payment for an assessed claim. The claim must be in \"assessed\"\nor \"partial_approval\" status before payment can be processed.\n\nPayment is recorded against the claim and linked to the billing/payments\nsubsystem. The claim transitions to \"paid\" once the payment is confirmed.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nSide effects: returns the constructed payment record and ledger entries with the claim status transitioned to paid, without persisting the changes. Emits an audit entry when audit is configured.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayClaimRequest" }, "examples": { "bank_transfer": { "summary": "Pay claim via bank transfer", "value": { "paid_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "payment_method": "bank_transfer", "payment_notes": "Final settlement \u2014 approved amount less policy excess", "processed_by": "payments-officer-mk-003", "metadata": { "bank_reference": "JPMC-ACH-2026030801", "beneficiary_account": "****4521", "beneficiary_bank": "JPMorgan Chase" } } }, "direct_settlement": { "summary": "Direct settlement to service provider (health)", "value": { "paid_amount": { "amount_minor": 115000000, "currency_code": "ngn" }, "payment_method": "direct_settlement", "payment_notes": "Direct settlement to hospital per authorisation reference PA-2026-LUTH-0088", "processed_by": "claims-auto-pay", "authorisation_id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "metadata": { "provider_reference": "LUTH-INV-2026-4455", "pre_auth_reference": "PA-2026-LUTH-0088" } } } } } } }, "responses": { "200": { "description": "Payment processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayClaimResponse" }, "examples": { "payment_processed": { "summary": "Payment confirmed", "value": { "data": { "id": "1724e0cd-6c5f-5bc3-a252-3e03f4c4a43b", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "payment_id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount_paid": { "amount_minor": 8000000, "currency_code": "zar" }, "payment_method": "bank_transfer", "processed_at": "2026-03-10T10:00:00Z", "processed_by": "payments-officer-mk-003", "status": "completed", "authorisation_id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "authorisation_gate_outcome": "clear" }, "ledger_entries": [ { "id": "b02b9190-8861-571a-9c77-e5ca374c70b7", "type": "claim_payment", "amount_minor": 8000000 } ], "status": "success", "message": "Claim payment processed successfully", "telemetry": { "total_ms": 64, "handler_ms": 58, "trace_id": "mno345" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failure. Codes: INVALID_STATE_TRANSITION,\nINVALID_MONETARY_AMOUNT, AUTHORISATION_PAYMENT_BLOCKED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "Invalid state transition", "value": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Invalid State Transition", "detail": "Claim must be assessed or partial_approval to process payment, current status: under_review" } ] } }, "invalid_amount": { "summary": "Invalid monetary amount", "value": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "paid_amount must be a positive integer in cents" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/close": { "post": { "operationId": "closeClaim", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the claim close workflow and terminal-state authority are implemented.", "source": "runtime source" }, "summary": "Close a claim", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the claim close workflow, terminal-state authority, and\nirreversible closure audit semantics are implemented.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "closure_reason": { "type": "string", "description": "Reason for closing the claim", "example": "Final settlement disbursed and accepted by claimant" }, "closed_by": { "type": "string", "description": "Identifier of the user or system closing the claim", "example": "claims-manager-001" } }, "additionalProperties": false }, "examples": { "paid_closure": { "summary": "Close after payment", "value": { "closure_reason": "Final settlement disbursed and accepted by claimant", "closed_by": "claims-manager-001" } }, "withdrawn": { "summary": "Close due to withdrawal", "value": { "closure_reason": "Claimant withdrew the claim on 2026-03-10", "closed_by": "claims-officer-015" } } } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Claim not in a closeable state (INVALID_STATE_TRANSITION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Validation Error", "detail": "Claim cannot perform close from status submitted" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Claim closure is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/pdf": { "get": { "operationId": "generateClaimPDF", "summary": "Generate a claim PDF report", "description": "Generate a PDF document summarising the claim, including the event details,\nassessment results, payment information, and workflow history.\n\nThe PDF is generated on demand and returned as a binary response. For large\nclaims with extensive documentation, generation may take several seconds.\n\nThe generated PDF includes:\n- Claim header (claim number, policy number, status)\n- Event details and description\n- Claim items with amounts\n- Assessment summary and notes\n- Payment details (if applicable)\n- Workflow timeline\n\nThis endpoint returns binary PDF data (application/pdf), not a JSON envelope.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "PDF generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded PDF", "schema": { "type": "string", "example": "attachment; filename=\"CLM-2026-00042.pdf\"" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves": { "post": { "operationId": "createReserve", "summary": "Create a claim reserve", "description": "Create a new active reserve for a claim. The amount must be a positive\ninteger in cents. On success the reserve is created with state \"active\",\ncurrent_amount == initial_amount, and released_amount == 0.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reserve_type", "amount" ], "properties": { "reserve_type": { "type": "string", "example": "case_estimate" }, "amount": { "type": "integer", "format": "int64", "example": 500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string", "example": "initial case estimate" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Reserve created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "description": "Validation error (zero or negative amount)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "initial_amount must be a positive integer in cents" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listClaimReserves", "summary": "List reserves for a claim", "description": "Retrieve all reserves for a claim, ordered by established_at descending.\nReturns explanation-ready reserve facts.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "Reserves retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveListResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves/{reserveId}": { "get": { "operationId": "getReserve", "summary": "Get a single reserve", "description": "Retrieve a single reserve by ID with explanation-ready facts.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "responses": { "200": { "description": "Reserve retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "patch": { "operationId": "updateReserve", "summary": "Update an active reserve", "description": "Only reserves in \"active\" state can be updated.", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 600000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves/{reserveId}/release": { "post": { "operationId": "releaseReserve", "summary": "Release reserve amount", "description": "Partial release yields \"partially_released\"; full release yields\n\"fully_released\". Over-release returns HTTP 422.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 300000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Over-release or invalid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves/{reserveId}/cancel": { "post": { "operationId": "cancelReserve", "summary": "Cancel an active reserve", "description": "Only reserves in \"active\" state can be cancelled. Returns inactive\nreserve with zero remaining exposure.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Reserve not in active state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves/{reserveId}/reestablish": { "post": { "operationId": "reestablishReserve", "summary": "Re-establish a terminal reserve", "description": "Create a new active reserve linked to a terminal predecessor.\nRe-establishment from \"active\" or \"partially_released\" is rejected.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 750000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Reserve re-established", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReestablishReserveResponse" } } } }, "422": { "description": "Reserve not terminal or invalid amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/reserves": { "get": { "operationId": "listPolicyReserves", "summary": "List reserves by policy", "description": "policy_id query parameter is required.", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "policy_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Reserves retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveListResponse" } } } }, "400": { "description": "Missing policy_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "active_only" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/investigations": { "post": { "operationId": "createOrAdvanceInvestigation", "summary": "Create or advance an SIU investigation", "description": "Create a new SIU investigation on a claim, or advance an existing open\ninvestigation by exactly one state. The endpoint uses create-or-advance\nsemantics: the first POST with `target_state=assigned` creates the\ninvestigation (HTTP 201); subsequent POSTs advance the open investigation\n(HTTP 200).\n\nState machine: assigned \u2192 investigating \u2192 findings_submitted \u2192 closed.\nDisposition (substantiated|unsubstantiated|settled) is required only when\n`target_state=closed`.\n\n`settled` closes the SIU investigation only \u2014 it does not change claim\nstatus, create recovery, or affect normal adjudication.\n\nEvery transition persists immutable evidence and an explanation tree in the\nsame transaction (governed contract). Actor provenance is sourced\nfrom the authenticated request context (governed contract).\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_state" ], "properties": { "target_state": { "type": "string", "enum": [ "assigned", "investigating", "findings_submitted", "closed" ], "description": "The target workflow state for this transition." }, "trigger_source": { "type": "string", "enum": [ "rule_threshold", "human_referral" ], "description": "Required on creation; immutable on subsequent advances." }, "assigned_party_id": { "type": "string", "description": "Required on creation; immutable on subsequent advances.", "x-axiom-identifier-classification": "party-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "assigned_role_type": { "type": "string", "description": "Required on creation; immutable on subsequent advances." }, "reason": { "type": "string", "description": "Required on creation." }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "description": "Required and non-empty on creation." }, "fraud_rule_refs": { "type": "array", "items": { "type": "string" }, "description": "Required and non-empty when trigger_source=rule_threshold." }, "disposition": { "type": "string", "enum": [ "substantiated", "unsubstantiated", "settled" ], "description": "Required when target_state=closed; forbidden otherwise." } }, "additionalProperties": false }, "examples": { "create_investigation": { "summary": "Create a new investigation (rule-triggered)", "value": { "target_state": "assigned", "trigger_source": "rule_threshold", "assigned_party_id": "party-siu-001", "assigned_role_type": "siu_investigator", "reason": "Fraud score 0.87 exceeded investigation threshold", "evidence_refs": [ "ev-fraud-score-001" ], "fraud_rule_refs": [ "rule-velocity-001", "rule-amount-002" ] } }, "advance_to_investigating": { "summary": "Advance to investigating", "value": { "target_state": "investigating" } }, "close_investigation": { "summary": "Close with disposition", "value": { "target_state": "closed", "disposition": "substantiated" } } } } } }, "responses": { "200": { "description": "Investigation advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationResponse" }, "example": { "data": { "id": "inv-001", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "state": "investigating" }, "status": "success", "message": "Investigation advanced", "telemetry": { "total_ms": 19, "handler_ms": 15, "trace_id": "vwx234" } } } } }, "201": { "description": "Investigation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationResponse" }, "example": { "data": { "id": "inv-001", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "state": "assigned", "trigger_source": "rule_threshold", "assigned_party_id": "party-siu-001", "assigned_role_type": "siu_investigator" }, "status": "success", "message": "Investigation created", "telemetry": { "total_ms": 28, "handler_ms": 24, "trace_id": "stu901" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{claimId}/recoveries": { "post": { "operationId": "createRecovery", "summary": "Record a recovery event for a claim", "description": "Records a subrogation or salvage recovery event with balanced ledger posting,\nexplanation tree, and evidence \u2014 all atomically in a single transaction.\nRequires X-Tenant-Context and Idempotency-Key headers.\n", "tags": [ "Claim" ], "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecoveryRequest" } } } }, "responses": { "200": { "description": "Idempotent replay \u2014 original response returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEnvelopeResponse" } } } }, "201": { "description": "Recovery recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEnvelopeResponse" } } } }, "404": { "description": "Claim not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict \u2014 same key, different payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{claimId}/recoveries/{recoveryId}/corrections": { "post": { "operationId": "createCorrection", "summary": "Record a correction for a recovery event", "description": "Creates a correction (full reversal, partial reversal, or write-off) for an\nexisting recovery using compensating ledger entries. Never deletes or updates\noriginal entries (governed contract). Requires X-Tenant-Context and Idempotency-Key headers.\n", "tags": [ "Claim" ], "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recoveryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCorrectionRequest" } } } }, "responses": { "200": { "description": "Idempotent replay \u2014 original response returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionEnvelopeResponse" } } } }, "201": { "description": "Correction recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionEnvelopeResponse" } } } }, "404": { "description": "Recovery not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict \u2014 same key, different payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/assertions": { "get": { "operationId": "listAssertions", "summary": "List assertions", "description": "Retrieve a cursor-paginated list of assertions for the operating tenant\n(tenant-isolated). Results are sorted by recorded_at descending\n(newest physical write first), tie-broken by id for stable pagination.\n\nFilter by event_id, cover_id, rule_version_id, and/or status (query\nparams). A bogus status value returns 400 with the accepted set in the\nerror meta. Legacy limit/offset pagination is rejected; clients must use\npage[size] and page[after].\n\nResponse uses the canonical success envelope format with cursor metadata.\n", "tags": [ "Assertion" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "event_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Filter to assertions responding to this event" }, { "name": "cover_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Filter to assertions determined under this cover" }, { "name": "rule_version_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Filter to assertions produced by this rule version" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "settled", "reopened", "adjusted", "finalised" ] }, "description": "Filter to assertions in this lifecycle status" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of assertions to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" } ], "responses": { "200": { "description": "Assertions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssertionListResponse" }, "examples": { "assertions_list": { "summary": "Assertions for an event", "value": { "data": [ { "id": "07805e66-69d7-5b42-a978-32729404b560", "logical_assertion_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "event_id": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "cover_id": "cov_01j9zxkp8wqrm2n4v6t5s3d7f1", "rule_version_id": "rv_01j9zxkp8wqrm2n4v6t5s3d7f1", "label_logical_entry_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "status": "settled", "payload": { "decision": "approved" }, "amount_minor": 8000000, "currency_code": "zar", "valid_from": "2026-03-08T16:00:00Z", "asserted_from": "2026-03-08T16:00:00Z", "recorded_at": "2026-03-08T16:00:01Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "event_id", "cover_id", "rule_version_id", "status" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/assertions/{id}": { "get": { "operationId": "getAssertion", "summary": "Get an assertion by ID", "description": "Retrieve a single assertion by its physical row UUID, scoped to the\noperating tenant (tenant-isolated). A cross-tenant id returns\n404.\n\nResponse uses the canonical success envelope format.\n", "tags": [ "Assertion" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique assertion identifier (physical row UUID)" } ], "responses": { "200": { "description": "Assertion retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssertionResponse" }, "examples": { "settled_assertion": { "summary": "A settled assertion", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "logical_assertion_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "event_id": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "cover_id": "cov_01j9zxkp8wqrm2n4v6t5s3d7f1", "rule_version_id": "rv_01j9zxkp8wqrm2n4v6t5s3d7f1", "label_logical_entry_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "status": "settled", "payload": { "decision": "approved" }, "amount_minor": 8000000, "currency_code": "zar", "valid_from": "2026-03-08T16:00:00Z", "asserted_from": "2026-03-08T16:00:00Z", "recorded_at": "2026-03-08T16:00:01Z" }, "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums": { "get": { "operationId": "listPremiums", "summary": "List premiums", "description": "Retrieve a paginated list of aggregate premium records for the operating\ntenant (one Premium per policy, the contract model). Cursor-paginated with\n`page[size]` default 20 / max 100 and opaque `page[after]` cursors.\nLegacy `limit` and `offset` query parameters are rejected.\n\nThe `policy_id` / `party_id` filter parameters are validated fail-loud (a\nmalformed typed-prefix value returns `400`, governed contract); they compose with the\noperating-tenant tenant-isolated scope, never widen it.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of premiums to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only premiums for this policy.\nAccepts the canonical typed-prefix policy id (`pol_\u2026`, governed contract).\nA malformed value returns 400. Absent = all premiums for the tenant.\nComposes with the existing operating-tenant tenant-isolated scope; never widens it.\n" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only premiums owed by this party (the premium\ndebtor / policyholder). Accepts the canonical typed-prefix party id\n(`pty_\u2026`, governed contract). A malformed value returns 400. Absent = all\npremiums for the tenant. Composes with the existing operating-tenant\ntenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Premiums retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumListResponse" }, "examples": { "premium_list": { "summary": "Aggregate premiums across policies", "value": { "data": [ { "id": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "active", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 12, "installment_amount_minor": 10417, "payment_frequency": "monthly", "effective_date": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" }, { "id": "f5550bad-c878-56c6-a82d-622720f34dcc", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "premium_type": "renewal", "status": "draft", "currency": "gbp", "base_premium": 9550, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 9550, "final_premium": 9550, "installment_count": 1, "installment_amount_minor": 9550, "payment_frequency": "annual", "effective_date": "2026-02-15T00:00:00Z", "created_at": "2026-01-15T00:00:00Z", "updated_at": "2026-01-15T00:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPremium", "summary": "Create a premium record", "description": "Persist a new aggregate premium (inflow-obligation) record for a policy and\nreturn it with `201 Created`. Exactly one Premium exists per policy\n(the (tenant context, policy_id) uniqueness constraint, the contract model) \u2014 a create for a policy\nthat already has a premium fails loud with `409 Conflict`.\n\nThis persists a manually-entered / imported inflow-obligation record at\n`status=draft`. It is NOT a rated premium decision \u2014 the rated path is\n`POST /v1/premiums/calculate`, which evaluates versioned CEL rules and emits\nan explanation tree. A draft obligation carries no rating decision to\nexplain (platform principle untouched).\n\nThe premium is scoped to the operating tenant \u2014 `tenant context` is taken from the\ntenant-context, never the request body. Intentional defaults applied on\ncreate (documented, not silent): `status=draft`, `premium_type` defaults to\n`initial`, and an unrated draft sets `base_premium = net_premium =\nfinal_premium = amount.amount_minor` (no discounts/commission yet, contract rule).\n\nIdempotent via the `Idempotency-Key` header: same key + same body returns the\noriginal `201`; same key + different body returns `409`.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "amount" ], "properties": { "policy_id": { "type": "string", "description": "Reference to the policy this premium belongs to, in the canonical\ntyped-prefix form (`pol_\u2026`, governed contract). A bare UUID is also\naccepted. A malformed value returns 400.\n", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Premium amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "premium_type": { "type": "string", "description": "Optional classifier on the aggregate premium (defaults to\n`initial` when omitted, contract rule). E.g. `initial`, `renewal`,\n`endorsement`, `adjustment`.\n", "example": "initial" }, "party_id": { "type": "string", "description": "Optional reference to the party who owes this premium, in the\ncanonical typed-prefix form (`pty_\u2026`, governed contract). A bare UUID is\nalso accepted. A malformed value returns 400.\n", "example": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "examples": { "monthly_debit_order": { "summary": "Draft inflow obligation (ZAR)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "amount": { "amount_minor": 125000, "currency_code": "zar" }, "premium_type": "initial" } }, "endorsement_adjustment": { "summary": "Endorsement premium adjustment (UK)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "amount": { "amount_minor": 2250, "currency_code": "gbp" }, "premium_type": "endorsement" } }, "with_party": { "summary": "Annual premium with explicit debtor party (Japan)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0c", "amount": { "amount_minor": 48000000, "currency_code": "jpy" }, "premium_type": "renewal", "party_id": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a" } } } } } }, "responses": { "201": { "description": "Premium created and persisted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumResponse" }, "examples": { "premium_created": { "summary": "Draft premium created", "value": { "data": { "id": "db6f76d9-4b0b-5ac0-ae58-3bc9564b5f8f", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "draft", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 1, "installment_amount_minor": 125000, "payment_frequency": "annual", "effective_date": "2026-03-12T08:00:00Z", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Premium created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}": { "get": { "operationId": "getPremium", "summary": "Get a premium by ID", "description": "Retrieve a single premium record by its unique identifier.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique premium identifier" } ], "responses": { "200": { "description": "Premium retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumResponse" }, "examples": { "active_premium": { "summary": "Active aggregate premium", "value": { "data": { "id": "e70f8626-562d-58ed-b6a0-ca46a5ce7627", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "party_id": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "active", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 12, "installment_amount_minor": 10417, "payment_frequency": "monthly", "effective_date": "2026-01-01T00:00:00Z", "due_date": "2026-04-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-03-02T08:30:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}/allocation": { "get": { "operationId": "getPremiumAllocation", "summary": "Get allocation snapshot for a premium", "description": "Returns the benefit-level allocation breakdown for a premium at a point in time.\nUses half-open temporal semantics under the governed contract.\n\nEach allocation row includes benefit_id, amount (Money object with amount_minor + currency_code), allocation_percentage_bps,\nallocation_basis, calculation_version, and allocation_rule_id (when basis is rule_based).\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Premium identifier" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time for temporal query (RFC3339). Defaults to now." } ], "responses": { "200": { "description": "Allocation snapshot retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-allocation-snapshots" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "premium_id", "benefit_id", "amount", "allocation_percentage_bps", "allocation_basis", "calculation_version", "effective_from" ], "properties": { "premium_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000 }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (malformed as_of timestamp)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "404": { "description": "No allocation snapshot found for this premium", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes": { "post": { "tags": [ "Policy" ], "summary": "Create a new quote", "description": "Creates a persisted premium calculation (quote) with a 30-minute TTL.\nExactly one of pricing_snapshot_id, products, or product_id must be provided.\n", "operationId": "createQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" } } } }, "responses": { "201": { "description": "Quote created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": { "age": 35, "vehicle_value": 25000 }, "covers_selected": [ "COMP", "TPL" ], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 42, "trace_id": "trace-abc123" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Actor attribution missing or invalid. Code: ACTOR_ATTRIBUTION_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure. Codes: PRICING_INPUT_REQUIRED,\nPRICING_INPUT_CONFLICT, EFFECTIVE_DATE_INVALID, EXPIRY_DATE_INVALID,\nSUPERSEDES_QUOTE_NOT_FOUND, TENANT_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "PRICING_INPUT_REQUIRED", "title": "Validation Error", "detail": "Exactly one of pricing_snapshot_id, products, or product_id must be provided" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "tags": [ "Policy" ], "summary": "List quotes by comparison reference", "description": "Returns all quotes for a given comparison_ref, ordered by created_at DESC.\nTenant-scoped to prevent cross-tenant leakage.\n", "operationId": "listQuotesByComparisonRef", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "comparison_ref", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comparison reference to filter quotes" } ], "responses": { "200": { "description": "Quotes matching the comparison reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteListResponse" }, "example": { "status": "success", "data": [ { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc", "comparison_ref": "cmp-xyz789" } ], "telemetry": { "total_ms": 18, "trace_id": "trace-def456" } } } } }, "422": { "description": "Missing comparison_ref (COMPARISON_REF_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.22 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "comparison_ref" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}": { "get": { "tags": [ "Policy" ], "summary": "Retrieve a quote by ID", "description": "Returns the persisted quote if active. Returns 404 for unknown IDs\n(including cross-tenant lookups) and 410 Gone for expired quotes.\n", "operationId": "getQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Active quote retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 12, "trace_id": "trace-ghi789" } } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "QUOTE_NOT_FOUND", "title": "Not Found", "detail": "Quote not found or belongs to a different tenant" } ] } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "410", "code": "QUOTE_EXPIRED", "title": "Gone", "detail": "Quote has expired (valid_until exceeded)" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/approve": { "post": { "tags": [ "Policy" ], "summary": "Approve a quote (indicative to firm)", "description": "Transitions a quote from indicative to firm status.\nRequires actor attribution (governed contract).\n", "operationId": "approveQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Quote approved (status changed to firm)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 15, "trace_id": "trace-jkl012" } } } } }, "401": { "description": "Actor attribution missing or invalid (ACTOR_ATTRIBUTION_REQUIRED).\n was 422 prior to this change.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid transition (INVALID_QUOTE_TRANSITION) or\nmissing tenant (TENANT_REQUIRED).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/decline": { "post": { "tags": [ "Policy" ], "summary": "Decline a quote", "description": "Transitions a quote to declined status. Requires a reason_code.\nRequires actor attribution (governed contract).\n", "operationId": "declineQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineQuoteRequest" } } } }, "responses": { "200": { "description": "Quote declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 11, "trace_id": "trace-mno345" } } } } }, "401": { "description": "Actor attribution missing or invalid (ACTOR_ATTRIBUTION_REQUIRED).\n was 422 prior to this change.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Missing reason_code (DECLINE_REASON_REQUIRED),\ninvalid transition (INVALID_QUOTE_TRANSITION), or\nmissing tenant (TENANT_REQUIRED).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/bind": { "post": { "tags": [ "Policy" ], "summary": "Bind a firm quote to create a policy", "description": "Binds a firm quote, creating a policy, premium allocation, ledger entries,\nand explanation tree. Only firm quotes can be bound.\nRequires actor attribution (governed contract).\n", "operationId": "bindQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Idempotency key for bind operations (required under the governed contract)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindQuoteRequest" } } } }, "responses": { "201": { "description": "Quote bound successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindQuoteResultResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "policy_id": "pol-xyz789", "premium_ids": [ "prm-abc001" ], "allocation_explanation_tree_id": "tree-001", "ledger_entry_ids": [ "led-001", "led-002" ] }, "telemetry": { "total_ms": 340, "trace_id": "trace-pqr678" } } } } }, "400": { "description": "Missing required input. Codes: IDEMPOTENCY_KEY_REQUIRED, INVALID_REQUEST.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "IDEMPOTENCY_KEY_REQUIRED", "title": "Bad Request", "detail": "Idempotency-Key header is required for bind operations" } ] } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "QUOTE_NOT_FOUND", "title": "Not Found", "detail": "Quote not found or belongs to a different tenant" } ] } } } }, "409": { "description": "Quote already bound (QUOTE_ALREADY_BOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "QUOTE_ALREADY_BOUND", "title": "Conflict", "detail": "Quote has already been bound to a policy" } ] } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "410", "code": "QUOTE_EXPIRED", "title": "Gone", "detail": "Quote has expired (valid_until exceeded)" } ] } } } }, "412": { "description": "Quote not in firm status (QUOTE_NOT_FIRM)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "412", "code": "QUOTE_NOT_FIRM", "title": "Precondition Failed", "detail": "Quote must be in firm status to bind" } ] } } } }, "422": { "description": "Validation failure. Codes: QUOTE_SNAPSHOT_INVALID,\nPREMIUM_DRIFT_EXCEEDED, LEDGER_IMBALANCED,\nQUOTE_PARTY_MISMATCH_REQUOTE_REQUIRED,\nSUPERSEDES_QUOTE_NOT_FOUND, TENANT_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "QUOTE_SNAPSHOT_INVALID", "title": "Validation Error", "detail": "Quote pricing snapshot is no longer valid" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/chain": { "get": { "tags": [ "Policy" ], "summary": "Get quote supersession chain", "description": "Returns the full supersession chain for a quote, ordered oldest-first.\nWalks backward through supersedes_quote_id links and reverses.\n", "operationId": "getQuoteChain", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Supersession chain (oldest-first)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteListResponse" }, "example": { "status": "success", "data": [ { "quote_id": "qte-earlier", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-09T10:00:00Z", "valid_until": "2026-06-09T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc", "supersedes_quote_id": "qte-earlier" } ], "telemetry": { "total_ms": 9, "trace_id": "trace-stu901" } } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/payments": { "get": { "operationId": "listPayments", "summary": "List payments", "description": "Retrieves a cursor-paginated list of payments for the current tenant.\n\nResults are sorted by created_at descending with id as a stable\ntie-breaker.\n\nUse `page[size]` and `page[after]` for pagination. Legacy `limit` and\n`offset` query parameters are rejected.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentListResponse" }, "example": { "data": [ { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "completed", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "reference_id": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "reference_type": "premium", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-01T08:30:00Z", "processed_at": "2026-04-01T08:30:00Z" }, { "id": "b02b9190-8861-571a-9c77-e5ca374c70b7", "amount": { "amount_minor": 340000, "currency_code": "gbp" }, "status": "pending", "payment_method": "bank_transfer", "description": "Quarterly premium \u2014 property all-risks POL-2026-00456", "reference_id": "aa2bc3a2-2c63-5c9f-bd68-6f1c49d6ba59", "reference_type": "premium", "created_at": "2026-04-02T09:15:00Z", "updated_at": "2026-04-02T09:15:00Z", "processed_at": null } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMlQwOToxNTowMFoiLCJpZCI6ImM5ZDBlMWYyLWEzYjQtNTY3OC1jZGVmLTc4OTAxMjM0NTY3OCJ9" }, "status": "success", "message": "Payments retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Creates a new payment record in `pending` status.\n\nThe payment is not processed immediately. Use the\n`POST /v1/payments/{id}/process` endpoint to initiate processing.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "example": { "amount": { "amount_minor": 275000, "currency_code": "kes" }, "payment_method": "bank_transfer", "description": "Annual premium \u2014 liability professional indemnity POL-2026-00789", "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7", "reference_type": "premium", "party_id": "07805e66-69d7-5b42-a978-32729404b560", "metadata": { "source": "broker-portal", "broker_id": "BRK-0087" } } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "1724e0cd-6c5f-5bc3-a252-3e03f4c4a43b", "amount": { "amount_minor": 275000, "currency_code": "kes" }, "status": "pending", "payment_method": "bank_transfer", "description": "Annual premium \u2014 liability professional indemnity POL-2026-00789", "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7", "reference_type": "premium", "party_id": "07805e66-69d7-5b42-a978-32729404b560", "metadata": { "source": "broker-portal", "broker_id": "BRK-0087" }, "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T10:00:00Z", "processed_at": null }, "status": "success", "message": "Payment created successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get a payment by ID", "description": "Retrieves a single payment by its unique identifier.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updatePayment", "summary": "Update a payment", "description": "Updates a payment record. Only payments in `pending` status can be updated.\n\nFields that can be updated: amount, currency, payment_method, description,\nreference_id, reference_type, metadata.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Updated payment amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Updated human-readable description", "example": "Adjusted monthly premium \u2014 motor comprehensive policy POL-2026-00123" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Updated reference to associated resource", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Updated type of referenced resource" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated extensible metadata" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Payment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}/process": { "post": { "operationId": "processPayment", "summary": "Process a payment", "description": "Initiates processing for a pending payment.\n\nTransitions the payment through the lifecycle:\n`pending` -> `processing` -> `completed` (or `failed`).\n\nThis is an asynchronous operation. The response confirms the payment\nhas been submitted for processing. Poll the payment status or use\nwebhooks to track completion.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment submitted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "processing", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-01T08:30:00Z", "processed_at": null }, "status": "success", "message": "Payment submitted for processing" } } } }, "400": { "description": "Bad request or payment is not in a processable state (INVALID_REQUEST)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Bad Request", "detail": "Payment is in 'completed' status and cannot be processed again" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}/cancel": { "post": { "operationId": "cancelPayment", "summary": "Cancel a payment", "description": "Cancels a payment. Only payments in `pending` or `processing` status\ncan be cancelled.\n\nTransitions the payment to `cancelled` status. This action cannot be undone.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "cancelled", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-03T11:00:00Z", "processed_at": null }, "status": "success", "message": "Payment cancelled successfully" } } } }, "400": { "description": "Bad request or payment is not in a cancellable state (INVALID_REQUEST)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Bad Request", "detail": "Payment is in 'completed' status and cannot be cancelled" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules": { "get": { "operationId": "listPaymentSchedules", "summary": "List payment schedules", "description": "Retrieves a cursor-paginated list of payment schedules for the current\ntenant.\n\nResults are derived from aggregate Premium rows and sorted by\neffective_date descending with id as a stable tie-breaker.\n\nPayment schedules define recurring cadence obligations tied to policies\n(e.g. monthly debit orders for motor premiums, quarterly bank transfers\nfor property cover). The list surface reports cadence definitions; per-\ninstalment paid/overdue state belongs to the payment settlement surface.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of payment schedules to return in this page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page.\nDo not construct or modify this value.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payment schedules retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentScheduleListResponse" }, "example": { "data": [ { "id": "24161ecd-8592-537c-849c-575aea8b40f1", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "frequency": "monthly", "amount": { "amount_minor": 125000, "currency_code": "zar" }, "status": "active", "next_due_date": "2026-05-01", "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-04-01T08:30:00Z" }, { "id": "002b084a-12bc-5d94-b2d6-40622d47fb4c", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "frequency": "quarterly", "amount": { "amount_minor": 850000, "currency_code": "zar" }, "status": "active", "next_due_date": "2026-07-01", "created_at": "2026-02-01T12:00:00Z", "updated_at": "2026-04-01T12:00:00Z" } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJlZmZlY3RpdmVfZGF0ZSI6IjIwMjYtMDItMDFUMDA6MDA6MDBaIiwiaWQiOiJhMmIzYzRkNS1lNmY3LTg5MDEtYmNkZS05MDEyMzQ1Njc4OTAifQ==" }, "status": "success", "message": "Payment schedules retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule creation workflow is implemented.", "source": "runtime source" }, "summary": "Create a payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule creation workflow is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "frequency", "amount", "currency", "next_due_date" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy this schedule services", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "frequency": { "$ref": "#/components/schemas/PaymentFrequency" }, "amount": { "type": "integer", "format": "int64", "description": "Scheduled payment amount per period in the smallest currency unit (e.g. cents). Exact integer representation.", "minimum": 0, "example": 420000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "EUR" }, "next_due_date": { "type": "string", "format": "date", "description": "First scheduled payment date", "example": "2026-06-01" } }, "additionalProperties": false }, "example": { "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "frequency": "half_yearly", "amount": 420000, "currency": "EUR", "next_due_date": "2026-06-01" } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule creation is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}": { "get": { "operationId": "getPaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule detail workflow is implemented.", "source": "runtime source" }, "summary": "Get a payment schedule by ID", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule detail workflow is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule detail retrieval is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}/pause": { "post": { "operationId": "pausePaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule state machine is implemented.", "source": "runtime payment-schedule handler" }, "summary": "Pause a payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule state machine is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule pause is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}/resume": { "post": { "operationId": "resumePaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule state machine is implemented.", "source": "runtime payment-schedule handler" }, "summary": "Resume a paused payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule state machine is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule resume is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices with cursor pagination", "description": "Retrieves a paginated list of invoices for the current tenant using\ncursor-based pagination under the governed contract.\n\nLegacy offset-based pagination (limit/offset query params) is rejected\nwith 400 LEGACY_PAGINATION.\n\nResults sorted by created_at descending.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 25, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Cursor for the next page (invoice ID from previous response)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoices retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "400": { "description": "Bad request. Codes: MISSING_TENANT, LEGACY_PAGINATION,\nINVALID_PAGE_SIZE, PAGE_SIZE_EXCEEDED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "legacy_pagination": { "summary": "Legacy pagination rejected", "value": { "errors": [ { "status": "400", "code": "LEGACY_PAGINATION", "title": "Legacy Pagination Not Supported", "detail": "Use page[size] and page[after] for cursor-based pagination under the governed contract" } ] } }, "invalid_page_size": { "summary": "Invalid page size", "value": { "errors": [ { "status": "400", "code": "INVALID_PAGE_SIZE", "title": "Invalid Page Size", "detail": "page[size] must be a positive integer" } ] } }, "page_size_exceeded": { "summary": "Page size exceeds maximum", "value": { "errors": [ { "status": "400", "code": "PAGE_SIZE_EXCEEDED", "title": "Page Size Exceeded", "detail": "page[size] must not exceed 100" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get a single invoice by ID", "description": "Retrieves a single invoice by its unique identifier.\nReturns 404 for unknown IDs or cross-tenant access attempts.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "id", "in": "path", "required": true, "description": "Invoice identifier", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing tenant header (MISSING_TENANT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } } } }, "404": { "description": "Invoice not found (INVOICE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "INVOICE_NOT_FOUND", "title": "Invoice Not Found", "detail": "The requested invoice does not exist or belongs to another tenant" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/invoices/{id}/finalize": { "post": { "operationId": "finalizeInvoice", "summary": "Finalize an invoice", "description": "Finalizes a draft invoice, making it immutable.\nRequires actor attribution headers under the governed contract.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-ID", "in": "header", "required": true, "description": "Actor identifier (governed contract)", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-Type", "in": "header", "required": true, "description": "Actor type (governed contract)", "schema": { "type": "string", "enum": [ "human", "service", "agent" ] } }, { "name": "id", "in": "path", "required": true, "description": "Invoice identifier", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "200": { "description": "Invoice finalized successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing required header. Codes: MISSING_TENANT,\nMISSING_ACTOR_ID, MISSING_ACTOR_TYPE.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "missing_actor_id": { "summary": "Missing actor ID header", "value": { "errors": [ { "status": "400", "code": "MISSING_ACTOR_ID", "title": "Missing Actor ID", "detail": "X-Actor-ID header is required for mutation endpoints" } ] } }, "missing_actor_type": { "summary": "Missing actor type header", "value": { "errors": [ { "status": "400", "code": "MISSING_ACTOR_TYPE", "title": "Missing Actor Type", "detail": "X-Actor-Type header is required for mutation endpoints" } ] } } } } } }, "404": { "description": "Invoice not found (INVOICE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "INVOICE_NOT_FOUND", "title": "Invoice Not Found", "detail": "The requested invoice does not exist or belongs to another tenant" } ] } } } }, "409": { "description": "Invoice already finalized (INVOICE_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "INVOICE_CONFLICT", "title": "Invoice Conflict", "detail": "Invoice has already been finalized and cannot be modified" } ] } } } }, "422": { "description": "Invalid invoice state (INVALID_INVOICE_STATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_INVOICE_STATE", "title": "Invalid Invoice State", "detail": "Invoice is not in a state that allows finalization" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/billing/cycles/close": { "post": { "operationId": "closeBillingCycle", "summary": "Close a billing cycle", "description": "Closes a billing cycle for the specified period, generating an invoice.\nRequires actor attribution headers under the governed contract.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-ID", "in": "header", "required": true, "description": "Actor identifier (governed contract)", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-Type", "in": "header", "required": true, "description": "Actor type (governed contract)", "schema": { "type": "string", "enum": [ "human", "service", "agent" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period_start", "period_end" ], "properties": { "period_start": { "type": "string", "format": "date-time", "description": "Start of the billing period (RFC3339)", "example": "2026-03-01T00:00:00Z" }, "period_end": { "type": "string", "format": "date-time", "description": "End of the billing period (RFC3339)", "example": "2026-03-31T23:59:59Z" }, "idempotency_key": { "type": "string", "description": "Optional idempotency key for deduplication" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Billing cycle closed and invoice created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing required header or invalid request body.\nCodes: MISSING_TENANT, MISSING_ACTOR_ID, MISSING_ACTOR_TYPE, INVALID_REQUEST.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "invalid_request": { "summary": "Invalid request body", "value": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Invalid Request", "detail": "Request body must include period_start and period_end in RFC3339 format" } ] } } } } } }, "409": { "description": "Invoice immutable conflict (INVOICE_IMMUTABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "INVOICE_IMMUTABLE", "title": "Billing Error", "detail": "Invoice for this period has already been finalized" } ] } } } }, "422": { "description": "Invalid cycle window (INVALID_CYCLE_WINDOW)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_CYCLE_WINDOW", "title": "Invalid Cycle Window", "detail": "period_end must be after period_start" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/accounts/{code}/balance": { "get": { "operationId": "getAccountBalance", "summary": "Get account balance", "description": "Computes and returns the balance for a specific ledger account.\n\nSupports point-in-time queries via the `as_of` parameter for\nhistorical balance lookups (as-was semantics per platform principle).\n\nThe response includes an explanation tree documenting the inputs,\nrule version, and computation method used.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "code", "in": "path", "required": true, "description": "Account code to query (e.g. PREM-RCV-001, CLM-PAY-001)", "schema": { "type": "string", "example": "PREM-RCV-001" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time for the balance computation (ISO 8601).\nIf omitted, returns the current balance.\n", "schema": { "type": "string", "format": "date-time", "example": "2026-03-31T23:59:59Z" } } ], "responses": { "200": { "description": "Account balance computed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResultResponse" }, "example": { "data": { "account_code": "PREM-RCV-001", "as_of": "2026-03-31T23:59:59Z", "currency": "USD", "amount": 4525075, "entry_count": 128, "explanation": { "inputs": { "account_code": "PREM-RCV-001", "date_from": "2026-01-01T00:00:00Z", "date_to": "2026-03-31T23:59:59Z", "include_pending": false }, "rule_version": "balance-calc-v2.1.0", "computation": "Sum of posted credits minus posted debits for account PREM-RCV-001", "entry_ids": [ "50447be1-27bd-5a7a-b51c-edce72303e3f", "ba8f3ab8-3beb-55dc-874f-040a4f50529a" ] } }, "status": "success", "message": "Account balance computed successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries/{entry_id}/reversals": { "post": { "operationId": "createReversal", "summary": "Create a ledger entry reversal", "description": "Creates a reversing entry for a previously posted ledger entry.\nThe original entry's status transitions to `reversed`, and a new\nentry with the opposite entry_type and same amount is created.\n\nThis preserves the full audit trail rather than modifying or\ndeleting the original entry (platform principle explainability).\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "entry_id", "in": "path", "required": true, "description": "Ledger entry UUID to reverse", "schema": { "type": "string", "format": "uuid", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason", "posted_by" ], "properties": { "reason": { "type": "string", "description": "Reason for the reversal (required for audit trail)", "example": "Incorrect account code \u2014 premium posted to claims payable in error" }, "posted_by": { "type": "string", "description": "User or service authorising the reversal", "example": "hello@axiom.express" }, "entry_date": { "type": "string", "format": "date-time", "description": "Accounting date for the reversal (defaults to now)", "example": "2026-04-01T00:00:00Z" } }, "additionalProperties": false }, "example": { "reason": "Incorrect account code \u2014 premium posted to claims payable in error", "posted_by": "hello@axiom.express", "entry_date": "2026-04-01T00:00:00Z" } } } }, "responses": { "201": { "description": "Reversal entry created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReversalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Entry has already been reversed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "STATE_CONFLICT", "title": "Conflict", "detail": "Ledger entry has already been reversed" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/integrity/verify": { "post": { "operationId": "verifyIntegrity", "summary": "Verify ledger integrity", "description": "Runs integrity checks on the ledger to detect anomalies such as\nunbalanced transactions, orphaned entries, or sequence gaps.\n\nThis is a read-only operation that does not modify any data.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_codes": { "type": "array", "items": { "type": "string" }, "description": "Restrict verification to specific accounts (all if omitted)", "example": [ "PREM-RCV-001" ] }, "date_from": { "type": "string", "format": "date-time", "description": "Start of verification period", "example": "2026-01-01T00:00:00Z" }, "date_to": { "type": "string", "format": "date-time", "description": "End of verification period", "example": "2026-03-31T23:59:59Z" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Integrity verification completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerIntegrityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries": { "get": { "operationId": "listLedgerEntries", "summary": "List ledger entries for the tenant", "description": "Returns the tenant's ledger entries (keyset-ordered by `entry_id`\nascending). Cursor-paginated under the governed contract: pass `page[size]`\nto bound the page and `page[after]` (an opaque cursor from a prior\nresponse's `meta.next_cursor`) to fetch the next page. Each entry is a\ndouble-entry posting line (governed contract); amounts are exact integer minor units.\n\nOptional `reference_id` filter narrows the list to the postings recorded\nagainst a single source reference (e.g. a claim, policy, premium, or\npayment id). Absent = all entries for the tenant. The filter composes with\nthe existing operating-tenant tenant-isolated scope; it never widens it.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only entries posted against this source\nreference id (`reference_id`, e.g. a claim / policy / premium /\npayment id). Absent = all entries for the tenant.\n" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of entries to return (cursor page size, governed contract)." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a prior response's `meta.next_cursor`. Treat as\nopaque; do not construct or modify. Omit to fetch the first page.\n" } ], "responses": { "200": { "description": "Ledger entries for the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEntryListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "reference_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries/{entry_id}/corrections": { "get": { "operationId": "getCorrections", "summary": "Get corrections for a ledger entry", "description": "Retrieves the correction history for a specific ledger entry,\nincluding any reversals and re-postings.\n\nResults sorted by created_at descending.\n\nThis supports the full audit trail and explainability requirements. \u2014 every correction is traceable back to the original entry.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "entry_id", "in": "path", "required": true, "description": "Original ledger entry UUID", "schema": { "type": "string", "format": "uuid", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Corrections retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCorrectionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets": { "post": { "operationId": "createRuleset", "summary": "Create a ruleset", "description": "Creates a new ruleset in `draft` status.\n\nRulesets are versioned containers of business rules that govern\ndomain rule lanes such as underwriting, pricing, claims assessment,\ndocument completeness, or discount composition. Rules are data. \u2014 explicit, versioned,\ndeterministic, and auditable.\n\nOptionally specify a `base_ruleset` code to inherit rules from\nan existing ruleset as a starting point.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRulesetRequest" }, "example": { "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" } } } } }, "responses": { "201": { "description": "Ruleset created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" }, "example": { "data": { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "status": "draft", "version": 1, "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" }, "rules": [], "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T10:00:00Z" }, "status": "success", "message": "Ruleset created successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listRulesets", "summary": "List rulesets", "description": "Retrieves a paginated list of rulesets for the current tenant.\n\nResults are sorted by `recorded_at` descending with the ruleset `id` as\na stable cursor tiebreaker. Legacy `limit` and `offset` query parameters\nare rejected; use `page[size]` and `page[after]`.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page", "schema": { "type": "string", "example": "eyJyZWNvcmRlZF9hdCI6IjIwMjYtMDgtMTVUMTI6MDA6MDBaIiwiaWQiOiJiMWMyZDNlNC1mNWE2LTc4OTAtYmNkZS1mMTIzNDU2Nzg5MDEifQ" } } ], "responses": { "200": { "description": "List of rulesets retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetListResponse" }, "example": { "data": [ { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "motor-comprehensive-v1", "name": "Motor Vehicle Rating Rules", "entity_type": "pricing", "description": "Validation and pricing rules for comprehensive motor insurance", "status": "active", "version": 3, "attributes": { "jurisdiction": "US", "product_line": "motor" }, "rules": null, "created_at": "2026-01-10T08:00:00Z", "updated_at": "2026-03-01T14:30:00Z" }, { "id": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "code": "property-allrisks-gb-v1", "name": "UK Property All-Risks", "entity_type": "underwriting", "description": "Validation and underwriting rules for all-risks property cover in the UK", "status": "draft", "version": 1, "attributes": { "jurisdiction": "GB", "product_line": "property" }, "rules": null, "created_at": "2026-03-15T09:00:00Z", "updated_at": "2026-03-15T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success", "message": "Rulesets retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}": { "get": { "operationId": "getRuleset", "summary": "Get a ruleset by ID", "description": "Retrieves a single ruleset by its unique identifier, including\nall associated business rules.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Ruleset retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateRuleset", "summary": "Update a ruleset", "description": "Updates the metadata of a ruleset (name, description, attributes).\n\nOnly rulesets in `draft` status can be updated. Active or deprecated\nrulesets are immutable \u2014 create a new version instead.\n\nThis does not modify individual rules. Use the rule-level endpoints\nto add, update, or remove rules.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated human-readable name", "example": "Motor Vehicle Rating Rules (Updated)" }, "description": { "type": "string", "description": "Updated description", "example": "Validation, pricing, and eligibility rules for comprehensive motor insurance" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated metadata", "example": { "jurisdiction": "US", "product_line": "motor", "effective_from": "2026-04-01" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Ruleset updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/test": { "post": { "operationId": "testRuleset", "summary": "Test a ruleset against input facts", "description": "Evaluates the entire ruleset against the provided input facts\nand returns the evaluation results.\n\nThis is a dry-run \u2014 no state is modified. The response includes\na full explanation tree showing which rules fired, their inputs,\nintermediate results, and final decisions (platform principle explainability).\n\nThe ruleset must be active before this endpoint runs. Testing a draft\nruleset returns `409 RULESET_NOT_ACTIVE`; use `/test-rule` for isolated\nexpression checks while authoring.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facts" ], "properties": { "facts": { "type": "object", "additionalProperties": true, "description": "Input facts for rule evaluation. Structure depends on the\nruleset's entity_type and the rules defined within it.\n", "example": { "applicant": { "age": 32, "licence_years": 10, "claims_history": 0 }, "vehicle": { "make": "Toyota", "model": "Hilux", "year_of_manufacture": 2023, "value": 450000 }, "cover": { "type": "comprehensive", "sum_insured": 450000 } } } }, "additionalProperties": false }, "example": { "facts": { "applicant": { "age": 32, "licence_years": 10, "claims_history": 0 }, "vehicle": { "make": "Toyota", "model": "Hilux", "year_of_manufacture": 2023, "value": 450000 }, "cover": { "type": "comprehensive", "sum_insured": 450000 } } } } } }, "responses": { "200": { "description": "Ruleset evaluation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/test-rule": { "post": { "operationId": "testSingleRule", "summary": "Test a single rule within a ruleset", "description": "Evaluates a single rule expression against the provided input facts.\nUseful for iterative rule development and debugging before the rule is\nadded to a ruleset.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expression", "data" ], "properties": { "expression": { "type": "string", "description": "CEL expression to test.", "example": "applicant.age >= 18" }, "data": { "type": "object", "additionalProperties": true, "description": "Input facts for rule evaluation", "example": { "applicant": { "age": 17, "licence_years": 0 } } } }, "additionalProperties": false }, "example": { "expression": "applicant.age >= 18", "data": { "applicant": { "age": 17, "licence_years": 0 } } } } } }, "responses": { "200": { "description": "Single rule evaluation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleRuleEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/deploy": { "post": { "operationId": "deployRuleset", "summary": "Deploy a ruleset", "description": "Transitions a ruleset from `draft` to `active` status, making it\navailable for evaluation in live policy, claim, and premium workflows.\n\nThis increments the ruleset version number. The previous active\nversion (if any) is transitioned to `deprecated` and retained\nfor as-was auditability.\n\nThis operation cannot be undone \u2014 to roll back, deploy the\nprevious version's rules in a new ruleset.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "activated_by" ], "properties": { "activated_by": { "type": "string", "description": "Actor identifier recorded in the deployment audit trail.", "example": "underwriter-user-003" } }, "additionalProperties": false }, "example": { "activated_by": "underwriter-user-003" } } } }, "responses": { "200": { "description": "Ruleset deployed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" }, "example": { "data": { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "status": "active", "version": 2, "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" }, "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T11:00:00Z" }, "status": "success", "message": "Ruleset deployed successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/rules": { "post": { "operationId": "addRule", "summary": "Add a rule to a ruleset", "description": "Adds a new business rule to a ruleset. The ruleset must be in\n`draft` status.\n\nRules are defined as CEL (Common Expression Language) expressions\nthat must be deterministic and side-effect free.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBusinessRuleRequest" }, "example": { "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": { "risk_category": "vehicle_eligibility" } } } } }, "responses": { "201": { "description": "Rule added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/rules/{ruleId}": { "put": { "operationId": "updateRule", "summary": "Update a rule within a ruleset", "description": "Updates an existing business rule within a ruleset. The ruleset\nmust be in `draft` status.\n\nUpdatable fields: name, expression, description, priority,\nstatus, attributes, conditions, actions.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } }, { "name": "ruleId", "in": "path", "required": true, "description": "Rule UUID identifier within the ruleset", "schema": { "type": "string", "format": "uuid", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated rule name", "example": "Maximum Vehicle Age (Extended)" }, "expression": { "type": "string", "description": "Updated CEL expression", "example": "vehicle.year_of_manufacture >= 2006" }, "description": { "type": "string", "nullable": true, "description": "Updated description", "example": "Vehicle must be no more than 20 years old for extended comprehensive cover" }, "priority": { "type": "integer", "description": "Updated execution priority", "example": 20 }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Updated rule status" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated metadata" }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" } }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Rule updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deleteRule", "summary": "Delete a rule from a ruleset", "description": "Removes a rule from a ruleset. The ruleset must be in `draft` status.\n\nRules in active or deprecated rulesets cannot be deleted \u2014 deprecate\nthe rule instead to preserve the audit trail.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } }, { "name": "ruleId", "in": "path", "required": true, "description": "Rule UUID identifier within the ruleset", "schema": { "type": "string", "format": "uuid", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe" } } ], "responses": { "200": { "description": "Rule deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetDeleteRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence": { "post": { "operationId": "createEvidenceRecord", "summary": "Create an evidence record", "description": "Creates a new evidence record capturing a decision, evaluation, or\nstate transition for audit and compliance purposes.\n\nEvidence records are immutable once created. The `content_hash` (SHA-256)\nis computed server-side and enables tamper detection.\n\nSupports platform principle (Explainability) \u2014 every material decision emits a durable\nexplanation tree stored as evidence.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvidenceRecordRequest" }, "example": { "record_type": "rule_evaluation", "subject_type": "policy", "subject_id": "e316666f-e293-5ccc-81a8-8a12fe4094c5", "content": { "evaluation": "premium_calculation", "inputs": { "vehicle_value": 450000, "driver_age": 32, "claims_history": 0, "region": "New York" }, "rule_version": "motor-pricing-v2.0.1", "base_premium": 8100, "loadings": [], "discounts": [ { "type": "no_claims_bonus", "percentage": 0.2 } ], "final_premium": 6480 }, "created_by": "pricing-engine" } } } }, "responses": { "201": { "description": "Evidence record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvidenceRecordResponse" }, "example": { "status": "success", "data": { "id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "type": "evidence", "attributes": { "evidence_id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "content_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "canonicalization_version": "jcs-rfc8785-v1" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}": { "get": { "operationId": "getEvidenceRecord", "summary": "Get an evidence record by ID", "description": "Returns a single evidence record including its full content payload\nand integrity hash.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evidence_id", "in": "path", "required": true, "description": "Evidence record UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "c0e531a6-9deb-53a8-873b-9736a707f52b" } ], "responses": { "200": { "description": "Evidence record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceRecordResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/query": { "post": { "operationId": "queryEvidence", "summary": "Query evidence records", "description": "Searches evidence records using structured filters. Supports filtering\nby subject, record type, date range, and content attributes.\n\nPOST is used instead of GET to support complex query payloads\nthat exceed URL length limits.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_type": { "type": "string", "description": "Filter by subject type", "example": "claim" }, "subject_id": { "type": "string", "description": "Filter by subject identifier", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "record_type": { "type": "string", "description": "Filter by evidence record type", "example": "decision_trace" }, "from_date": { "type": "string", "format": "date-time", "description": "Filter records created on or after this timestamp", "example": "2026-03-01T00:00:00Z" }, "to_date": { "type": "string", "format": "date-time", "description": "Filter records created before this timestamp", "example": "2026-03-12T23:59:59Z" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of records to skip" } }, "additionalProperties": false }, "example": { "subject_type": "claim", "subject_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "record_type": "decision_trace", "from_date": "2026-03-01T00:00:00Z", "limit": 50 } } } }, "responses": { "200": { "description": "Matching evidence records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryEvidenceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}/integrity-verifications": { "post": { "operationId": "verifyEvidenceIntegrity", "summary": "Verify integrity of a single evidence record", "description": "Recomputes the content hash for the specified evidence record and\ncompares it against the stored hash. Returns a verification result\nindicating whether the record has been tampered with.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evidence_id", "in": "path", "required": true, "description": "Evidence record UUID to verify", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "c0e531a6-9deb-53a8-873b-9736a707f52b" } ], "responses": { "201": { "description": "Integrity verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityVerificationResponse" }, "example": { "status": "success", "data": { "id": "d030a083-6627-5d10-a1ec-de4b762f556b", "type": "integrity-verification", "attributes": { "verification_id": "d030a083-6627-5d10-a1ec-de4b762f556b", "expected_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "actual_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "verified", "verified_at": "2026-03-12T10:20:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/verify": { "post": { "operationId": "verifyEvidence", "summary": "Batch-verify evidence record integrity", "description": "Verifies the integrity of multiple evidence records in a single request.\nUseful for periodic compliance audits or spot checks.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidence_ids" ], "properties": { "evidence_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of evidence record IDs to verify", "minItems": 1, "maxItems": 100 } }, "additionalProperties": false }, "example": { "evidence_ids": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "00548ee3-5ea2-5e09-8975-93b2e0fe033e" ] } } } }, "responses": { "200": { "description": "Batch verification results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEvidenceResponse" }, "example": { "status": "success", "data": [ { "record_id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "content_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "VERIFIED" }, { "record_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "content_hash": "4a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "TAMPERED" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/assemble": { "post": { "operationId": "assembleEvidencePack", "summary": "Assemble an evidence pack", "description": "Assembles a collection of evidence records into a named pack.\nEvidence packs provide a complete audit trail for a decision or event,\nbundling all related records for compliance reporting and review.\n\nunder the governed contract, packs are assembled on demand from existing records\nand are themselves immutable once created.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssembleEvidencePackRequest" }, "example": { "name": "Claim CLM-2026-00142 \u2014 Marine Cargo Adjudication Evidence Pack", "record_ids": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237" ], "assembled_by": "compliance-reporting-service" } } } }, "responses": { "200": { "description": "Evidence pack assembled", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidencePackResource" } }, "additionalProperties": true } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/{pack_id}": { "get": { "operationId": "getEvidencePack", "summary": "Get an evidence pack by ID", "description": "Returns an evidence pack including all constituent evidence records.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "pack_id", "in": "path", "required": true, "description": "Evidence pack UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "00548ee3-5ea2-5e09-8975-93b2e0fe033e" } ], "responses": { "200": { "description": "Evidence pack with records", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidencePackResource" } }, "additionalProperties": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/compliance/evaluations/{evaluation_id}/report": { "get": { "operationId": "getComplianceReport", "summary": "Get a compliance evaluation report", "description": "Returns a compliance report for a completed evaluation, including\nper-jurisdiction findings, pack metadata, and explanation tree reference.\n\nunder the governed contract: compliance_assertion is always false \u2014 reports are\nevidence-enabling, not compliance-asserting.\n", "tags": [ "Compliance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evaluation_id", "in": "path", "required": true, "description": "Compliance evaluation UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "6b6487c1-bf44-5a61-ad58-caf256e207b6" } ], "responses": { "200": { "description": "Compliance evaluation report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReportResponse" }, "example": { "data": { "evaluation_id": "6b6487c1-bf44-5a61-ad58-caf256e207b6", "generated_at": "2026-04-08T12:00:05Z", "compliance_assertion": false, "findings": [ { "jurisdiction_code": "ZA", "status": "pass", "evidence_references": [ "3af4d529-138b-545f-a71b-a5a04ba7e417" ], "missing_evidence": [] } ], "ruleset_metadata": [ { "pack_id": "7dba3076-6baa-5957-8f89-482edba4ea47", "pack_version": "1.0.0" } ], "explanation_tree_id": "f0a8077c-3895-5ef6-922c-e35461d34efd" }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/vendors": { "post": { "operationId": "createVendor", "summary": "Register a new vendor", "description": "Creates a vendor record for a third-party service provider.\n\nVendors represent external organisations that process, store, or access\ntenant data. Each vendor is tracked for compliance purposes (POPIA, GDPR)\nincluding data classification, security review status, and subprocessor chains.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorRequest" }, "example": { "data": { "type": "vendors", "attributes": { "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification for health insurance products", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "integrations": [ { "system_name": "MediCheck Claims API", "data_categories": [ "health_records" ], "data_direction": "ingress", "transfer_method": "rest_api" } ] } } } } } }, "responses": { "201": { "description": "Vendor created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" }, "example": { "data": { "type": "vendors", "attributes": { "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification for health insurance products", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "status": "draft", "integrations": [ { "integration_id": "ef3dae92-18c3-52d8-bb19-359e317362d6", "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "system_name": "MediCheck Claims API", "data_categories": [ "health_records" ], "data_direction": "ingress", "transfer_method": "rest_api" } ], "security_review_status": "pending", "security_review_approved_at": null, "created_at": "2026-03-12T10:00:00Z", "updated_at": "2026-03-12T10:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listVendors", "summary": "List vendors", "description": "Returns a paginated list of vendor records for the tenant.\n\nSupports cursor-based pagination via `page[size]` and `page[after]` query parameters.\nResponse uses a JSON:API-style collection envelope with `data` array and `meta` object.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of vendors to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor for next page; obtained from previous response meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of vendors", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "meta": { "type": "object", "properties": { "page_size": { "type": "integer" }, "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": [ { "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "status": "active", "created_at": "2026-02-01T09:00:00Z", "updated_at": "2026-03-05T16:20:00Z" }, { "vendor_id": "3164d499-6504-58ad-9020-f1f1377130f5", "name": "SafePay Financial Gateway", "purpose": "Premium collection and payment processing", "classification": "B", "accessed_data_classes": [ "financial", "personal_identifiable" ], "status": "active", "created_at": "2025-11-15T10:00:00Z", "updated_at": "2026-02-28T14:00:00Z" } ], "meta": { "page_size": 20, "next_cursor": "" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}": { "get": { "operationId": "getVendor", "summary": "Get a vendor by ID", "description": "Returns the full vendor record including integrations and subprocessors.\nResponse uses JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Vendor UUID identifier", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "responses": { "200": { "description": "Vendor record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "patch": { "operationId": "updateVendor", "summary": "Update a vendor", "description": "Partially updates a vendor record. Only provided fields are modified.\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Vendor UUID identifier", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorRequest" }, "example": { "data": { "type": "vendors", "attributes": { "status": "active", "security_review_status": "approved" } } } } } }, "responses": { "200": { "description": "Vendor updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}/subprocessors": { "post": { "operationId": "createSubprocessor", "summary": "Add a subprocessor to a vendor", "description": "Registers a subprocessor under a vendor. Subprocessors are third parties\nthat the vendor engages to process data on behalf of the tenant.\n\nTracking subprocessors is required for POPIA and GDPR compliance, ensuring\nthe full data processing chain is documented and approved.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Parent vendor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubprocessorRequest" }, "example": { "data": { "type": "subprocessors", "attributes": { "name": "Azure US East", "service_scope": "Disaster recovery and backup storage for policy documents" } } } } } }, "responses": { "201": { "description": "Subprocessor created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubprocessorDataEnvelope" }, "example": { "data": { "type": "subprocessors", "attributes": { "subprocessor_id": "d3216bd6-21dd-572a-8396-9e1444af9bfb", "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "Azure US East", "service_scope": "Disaster recovery and backup storage for policy documents", "approval_status": "pending", "approved_by": null, "approved_at": null, "change_reason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}/subprocessors/{subprocessor_id}": { "patch": { "operationId": "updateSubprocessor", "summary": "Update a subprocessor", "description": "Partially updates a subprocessor record under a vendor.\nTypically used to change approval status or update service scope.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Parent vendor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" }, { "name": "subprocessor_id", "in": "path", "required": true, "description": "Subprocessor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "d3216bd6-21dd-572a-8396-9e1444af9bfb" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubprocessorRequest" }, "example": { "data": { "type": "subprocessors", "attributes": { "approval_status": "approved", "change_reason": "Annual subprocessor review completed \u2014 SOC 2 Type II report verified" } } } } } }, "responses": { "200": { "description": "Subprocessor updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubprocessorDataEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/balance": { "get": { "operationId": "getBenefitBalance", "summary": "Get benefit balance", "description": "Returns the current balance for a specific benefit type on a policy,\nshowing how much of the benefit limit has been consumed.\n\nSupports point-in-time queries via `as_of` and period-scoped queries\nvia `period_start`/`period_end` for benefits with annual or periodic\nlimits (e.g. annual dental limit, per-incident excess cap).\n\nunder the governed contract, benefit balances are computed from the ledger and\nare always consistent with claim payouts and adjustments.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefits for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier (e.g. hospitalisation, dental,\noptical, roadside_assistance, personal_accident).\n", "schema": { "type": "string" }, "example": "hospitalisation" }, { "name": "period_start", "in": "query", "required": false, "description": "Start of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "period_end", "in": "query", "required": false, "description": "End of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time query. Returns the benefit balance as it was\nat this timestamp. Defaults to current time if omitted.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-03-12T00:00:00Z" } ], "responses": { "200": { "description": "Benefit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "balance", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit (decimal as string)", "example": "500000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount consumed (claimed and paid)", "example": "125000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "balance": { "type": "string", "description": "Remaining available balance", "example": "375000.00" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "period_start": { "type": "string", "format": "date", "description": "Start of the benefit period" }, "period_end": { "type": "string", "format": "date", "description": "End of the benefit period" }, "as_of": { "type": "string", "format": "date-time", "description": "Effective timestamp of the balance query" }, "claims_count": { "type": "integer", "description": "Number of claims consuming this benefit in the period" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "hospitalisation", "limit": "500000.00", "consumed": "125000.00", "balance": "375000.00", "currency": "USD", "period_start": "2026-01-01", "period_end": "2026-12-31", "as_of": "2026-03-12T00:00:00Z", "claims_count": 2 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type", "period_start", "period_end" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/available": { "get": { "operationId": "getBenefitAvailable", "summary": "Get available benefit amount", "description": "Returns the currently available (claimable) amount for a benefit type\non a policy, accounting for in-flight claims that have been filed\nbut not yet settled.\n\nThis differs from `/balance` in that it includes pending claims\nas reserved amounts, giving a more conservative view of availability\nsuitable for claim intake decisions.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefit availability for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier", "schema": { "type": "string" }, "example": "dental" } ], "responses": { "200": { "description": "Available benefit amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "reserved", "available", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit", "example": "25000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount from settled claims", "example": "8500.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reserved": { "type": "string", "description": "Amount reserved by pending (in-flight) claims", "example": "3200.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "available": { "type": "string", "description": "Amount available for new claims\n(limit - consumed - reserved)\n", "example": "13300.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "pending_claims": { "type": "integer", "description": "Number of in-flight claims reserving benefit", "example": 1 } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "dental", "limit": "25000.00", "consumed": "8500.00", "reserved": "3200.00", "available": "13300.00", "currency": "USD", "pending_claims": 1 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/proration-balances": { "get": { "description": "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.", "operationId": "getProrationBalance", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Policy ID in pol_ wire form.", "in": "query", "name": "policy_id", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Implemented proration balance consumer. `reinsurance_balance` is an accepted fail-closed value until governed treaty authority exists.\n", "in": "query", "name": "consumer", "required": true, "schema": { "enum": [ "fund_balance", "earning_balance", "reinsurance_balance" ], "type": "string" } }, { "description": "Inclusive balance period start.", "in": "query", "name": "period_start", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive balance period end.", "in": "query", "name": "period_end", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Fund account code, required for fund_balance unless account_code is supplied.", "in": "query", "name": "fund_account_code", "required": false, "schema": { "type": "string" } }, { "description": "Generic account code for fund or earning balance scope.", "in": "query", "name": "account_code", "required": false, "schema": { "type": "string" } }, { "description": "Earning period key, required for earning_balance unless account_code is supplied.", "in": "query", "name": "earning_period_key", "required": false, "schema": { "type": "string" } }, { "description": "Include constituent proration component IDs and operation details.", "in": "query", "name": "decompose", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationBalanceResponse" } } }, "description": "Proration balance result." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [ "policies:read" ] } ], "summary": "Get Proration Balance", "tags": [ "Premium", "Policy", "Benefit" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "consumer", "period_start", "period_end", "fund_account_code", "account_code", "earning_period_key", "decompose" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "policies:read" ], "required_permissions": [ "policies:read" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/dashboard": { "get": { "operationId": "getDashboardMetrics", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get dashboard metrics", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Dashboard analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/claims-by-status": { "get": { "operationId": "getClaimsByStatus", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get claims breakdown by status", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Claims-by-status analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/monthly-revenue": { "get": { "operationId": "getMonthlyRevenue", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get monthly revenue trend", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Monthly-revenue analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/top-products": { "get": { "operationId": "getTopProducts", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get top products by premium volume", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Top-products analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.22; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/reports/export": { "get": { "operationId": "exportReport", "summary": "Export a report", "description": "Generates and exports a report in the requested format (PDF or CSV).\n\nSupported report types:\n- `premium_collection` \u2014 Premium collection summary by product and period\n- `claims_register` \u2014 Claims register with status, amounts, and settlement details\n- `loss_ratio` \u2014 Loss ratio analysis by product line\n- `policy_register` \u2014 Policy register with coverage and premium details\n- `reconciliation` \u2014 Ledger reconciliation report\n- `commission_statement` \u2014 Broker commission statement\n\nThe response is the report file itself (binary content), not a\nJSON envelope.\n", "tags": [ "Report" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "type", "in": "query", "required": true, "description": "Report type to generate", "schema": { "type": "string", "enum": [ "premium_collection", "claims_register", "loss_ratio", "policy_register", "reconciliation", "commission_statement" ], "example": "premium_collection" } }, { "name": "format", "in": "query", "required": true, "description": "Output format for the report", "schema": { "type": "string", "enum": [ "pdf", "csv" ], "example": "pdf" } }, { "name": "date_from", "in": "query", "required": false, "description": "Start date for the report period (inclusive, ISO 8601 date)", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "required": false, "description": "End date for the report period (inclusive, ISO 8601 date)", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "product_code", "in": "query", "required": false, "description": "Filter report to a specific product code", "schema": { "type": "string", "example": "motor-comprehensive" } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary amounts (defaults to tenant base currency)", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } } ], "responses": { "200": { "description": "Report generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "PDF report binary content" } }, "text/csv": { "schema": { "type": "string", "description": "CSV report content" } } }, "headers": { "Content-Disposition": { "description": "Attachment filename for the downloaded report", "schema": { "type": "string", "example": "attachment; filename=\"premium-collection-2026-contract rule.pdf\"" } }, "Content-Length": { "description": "Size of the report file in bytes", "schema": { "type": "integer", "example": 245760 } } } }, "400": { "description": "Invalid report parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Invalid request", "detail": "unknown report type \"unknown\". Accepted: dashboard, claims-by-status, monthly-revenue, top-products" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "type", "format", "date_from", "date_to", "product_code", "currency" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/inbox/messages": { "post": { "operationId": "receiveInboxMessage", "summary": "Receive an inbound message", "description": "Accepts an inbound message into the Axiom inbox for processing.\n\nThe inbox is the single entry point for external messages (emails,\nnotifications, partner communications) entering the platform. Messages\nare deduplicated using the `deduplication_key` and routed to the\nappropriate processing workflow.\n\n**Response format:** canonical success envelope.\n\n**Idempotency:** Sending the same `deduplication_key` twice returns\nthe same `inbox_message_id` without creating a duplicate.\n", "tags": [ "Inbox" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "message_type", "deduplication_key", "payload" ], "properties": { "source": { "type": "string", "description": "Identifier of the message source system or channel\n(e.g. email gateway, partner API, broker portal).\n", "example": "partner-api-stripepay" }, "message_type": { "type": "string", "description": "Type classification for routing (e.g. claim_notification,\npayment_confirmation, policy_amendment_request, document_upload).\n", "example": "payment_confirmation" }, "deduplication_key": { "type": "string", "description": "Client-provided idempotency key. Messages with the same key\nare deduplicated \u2014 only the first is processed.\n", "example": "stripepay-txn-2026-03-12-00142" }, "payload": { "type": "object", "additionalProperties": true, "description": "Message payload. Structure varies by message_type.", "example": { "transaction_id": "TXN-2026-00142", "policy_number": "POL-US-2026-00089", "amount": "1250.00", "currency": "USD", "payment_date": "2026-03-12", "payment_method": "debit_order" } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata (timestamps, routing hints, source headers)", "example": { "received_from_ip": "203.0.113.42", "original_timestamp": "2026-03-12T10:05:00Z" } } }, "additionalProperties": false }, "examples": { "payment_confirmation": { "summary": "Premium payment confirmation from payment gateway", "value": { "source": "partner-api-stripepay", "message_type": "payment_confirmation", "deduplication_key": "stripepay-txn-2026-03-12-00142", "payload": { "transaction_id": "TXN-2026-00142", "policy_number": "POL-US-2026-00089", "amount": "1250.00", "currency": "USD", "payment_date": "2026-03-12", "payment_method": "debit_order" } } }, "claim_notification": { "summary": "First notification of loss from broker portal", "value": { "source": "broker-portal-v2", "message_type": "claim_notification", "deduplication_key": "broker-fnol-2026-03-12-A7891", "payload": { "broker_reference": "BRK-A7891", "policy_number": "POL-KE-2026-00034", "incident_date": "2026-03-10", "incident_type": "property_damage", "description": "Fire damage to warehouse contents \u2014 Mombasa port facility", "estimated_loss": "5200000.00", "currency": "KES" } } } } } } }, "responses": { "202": { "description": "Message accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMessageReceiptResponse" }, "example": { "status": "success", "data": { "inbox_message_id": "866808e8-4d34-5e90-8808-1845d852ace8", "receipt_status": "accepted", "deduplication_key": "stripepay-txn-2026-03-12-00142" }, "telemetry": { "request_id": "req_01j8example" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "published-429-response", "headers": [ "Retry-After", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" ], "numeric_commitment": "tenant-policy-runtime", "limit_source": "active tenant rate_limit_policies.limit", "window_source": "active tenant rate_limit_policies.window_secs", "enforcement": "gateway-rate-limit-runtime" } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ingress/events": { "post": { "operationId": "ingestEvent", "summary": "Ingest an event", "description": "Accepts an event into the Axiom ingress pipeline for processing.\n\nThis is an admitted alpha transport surface for asynchronous external\ninputs. It persists a durable inbox record and returns 202 Accepted\nbefore downstream processing. It is not a public self-service event\ncatalogue, and event-type schemas are not yet published as a generated\ncontract fragment. Event types, payload schemas, and promotion rules are\ntenant-owned configuration when promoted; they are not Axiom-owned public\ndomain content.\n\n**Conditional availability:** This endpoint may return 404 if async\ningress is not enabled in the environment.\n\n**Response format:** JSON:API style \u2014 not the legacy wrapper.\n\n**Idempotency:** Events are deduplicated using `X-Webhook-Delivery-ID`\nwhen supplied. If the header is absent, the runtime derives a stable key\nfrom the source and request body bytes. Resubmitting the same key returns\nthe original `ingress_id`.\n", "tags": [ "Ingress" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_type", "payload" ], "properties": { "event_type": { "type": "string", "description": "Tenant-owned external event type identifier. The public\ndeveloper-preview contract does not publish a stable event\ntype catalogue; use only values supplied in an issued tenant\nintegration runbook.\n", "example": "external.event.received" }, "source": { "type": "string", "description": "Optional source hint. The runtime may derive source from the\nauthenticated context or `X-Source` header.\n", "example": "external-ingress" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event actually occurred (as opposed to when it was\nreceived). If omitted, the server uses the receipt timestamp.\n", "example": "2026-03-12T09:30:00Z" }, "payload": { "type": "object", "additionalProperties": true, "description": "Tenant-owned boundary payload. Structure varies by event_type.\nNo public self-service payload schema catalogue is published\nin API 0.1.0. Treat payload shape as tenant-issued integration\nconfiguration, not Axiom-owned domain content.\n" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional event metadata (routing hints, trace context)" } }, "additionalProperties": false }, "examples": { "event_received": { "summary": "External event received", "value": { "event_type": "external.event.received", "source": "external-ingress", "occurred_at": "2026-03-12T09:30:00Z", "payload": { "external_reference": "event-2026-03-12-001", "occurred_at": "2026-03-12T09:30:00Z", "attributes": { "status": "received" } } } }, "event_with_metadata": { "summary": "External event with metadata", "value": { "event_type": "external.event.updated", "source": "external-ingress", "occurred_at": "2026-03-12T06:00:00Z", "payload": { "external_reference": "event-2026-03-12-002", "attributes": { "status": "updated" } }, "metadata": { "import_batch": "batch-2026-03-12" } } } } } } }, "responses": { "202": { "description": "Event accepted for processing", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "ingress_id", "correlation_id", "idempotency_key", "received_at" ], "properties": { "status": { "type": "string", "enum": [ "accepted" ] }, "ingress_id": { "type": "string", "format": "uuid", "description": "Assigned ingress record identifier", "x-axiom-identifier-shape": "uuid" }, "correlation_id": { "type": "string", "format": "uuid", "description": "Correlation ID for tracing this event through the pipeline", "x-axiom-identifier-shape": "uuid" }, "idempotency_key": { "type": "string", "description": "Echo of the supplied or runtime-derived idempotency key" }, "received_at": { "type": "string", "format": "date-time", "description": "Server-side receipt timestamp" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": { "status": "accepted", "ingress_id": "491eb158-40d7-5094-9cf3-3e7a7b38fab6", "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "idempotency_key": "external-ingress:event-2026-03-12-001", "received_at": "2026-03-12T09:30:05Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Async ingress is not enabled for the admitted environment.\nContact support to enable it.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "FEATURE_DISABLED", "title": "Not Found", "detail": "Event ingress is not enabled in this environment" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "published-429-response", "headers": [ "Retry-After", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" ], "numeric_commitment": "tenant-policy-runtime", "limit_source": "active tenant rate_limit_policies.limit", "window_source": "active tenant rate_limit_policies.window_secs", "enforcement": "gateway-rate-limit-runtime" } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/mailroom/webhook-endpoints": { "post": { "operationId": "registerWebhookEndpoint", "summary": "Register a webhook endpoint", "description": "Registers or updates a tenant-scoped outbound webhook endpoint.\n\nThis is an alpha transport-configuration surface governed by the\nMailroom transport registry, not an ordinary product API operation.\nIt records where outbound webhook deliveries may be sent and how the\ndelivery should be authenticated. Event subscription catalogues and\ndelivery routing rules are not yet published as a public self-service\ncontract. Do not send `event_types`, event schemas, routing rules,\nordering keys, or replay policy in this request; those semantics are\ngoverned separately before publication.\n\nSecrets are supplied by reference only. Do not send raw secret material\nin the request body.\n\nFor `auth_method=hmac_sha256`, each outbound delivery includes:\n- `X-Axiom-Delivery-Id`: typed `whd_` durable delivery id.\n- `X-Correlation-ID`: support trace id for the delivery workflow.\n- `X-Webhook-Timestamp`: Unix seconds in UTC.\n- `X-Webhook-Signature`: `sha256=` where the digest is\n `HMAC-SHA256(secret, X-Webhook-Timestamp + \".\" + raw request body bytes)`.\n\nReceivers should reject missing, malformed, stale, or mismatched\nsignatures before processing the payload. A five-minute replay window is\nthe alpha recommendation unless the issued integration runbook specifies\na stricter tenant policy.\n\nOutbound webhook delivery is at-least-once. Exactly-once delivery,\nglobal ordering, and per-endpoint ordering are not guaranteed in the\nalpha public contract. The same `X-Axiom-Delivery-Id` is reused across\nretry attempts for one delivery record, but it is not a stable canonical\nevent id across endpoints, event streams, or schema revisions. Receivers\nmust be idempotent and tolerate duplicate, delayed, and out-of-order\ndeliveries.\n\n**Response format:** Canonical success envelope.\n", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "auth_method", "max_retries", "backoff_seconds" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Tenant-scoped endpoint name. Reusing the same name updates\nmutable endpoint settings.\n", "example": "primary-events" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL where webhook payloads will be delivered.\nRuntime validation rejects non-HTTPS URLs and known private,\nloopback, link-local, and non-routable targets.\n", "example": "https://receiver.example.com/axiom/webhooks" }, "description": { "type": "string", "description": "Human-readable description of this endpoint's purpose.", "example": "Primary outbound event receiver" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ], "default": "hmac_sha256", "description": "Authentication method for webhook deliveries.\n- hmac_sha256: HMAC signature over timestamp and raw body bytes.\n- bearer_token_ref: bearer token resolved from auth_secret_ref at dispatch time.\n- none: unsigned delivery; admitted only where tenant policy allows it.\n", "example": "hmac_sha256" }, "auth_secret_ref": { "type": "string", "writeOnly": true, "description": "Opaque secret reference resolved by the Mailroom dispatcher.\nRequired when auth_method is hmac_sha256 or bearer_token_ref.\nRaw secret material must not be sent in this field.\n", "example": "ref:webhooks/primary-events-signing-key" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the endpoint is active" }, "max_retries": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Number of retry attempts after the first delivery attempt.", "example": 3 }, "backoff_seconds": { "type": "array", "description": "Retry backoff values in seconds. The array length must equal\nmax_retries; each value must be between 1 and 3600 seconds.\n", "items": { "type": "integer", "minimum": 1, "maximum": 3600 }, "example": [ 10, 30, 60 ] } }, "additionalProperties": false }, "examples": { "hmac_endpoint": { "summary": "HMAC-signed endpoint", "value": { "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": [ 10, 30, 60 ], "enabled": true } }, "unsigned_endpoint": { "summary": "Unsigned endpoint admitted by tenant policy", "value": { "name": "test-events", "url": "https://receiver.example.com/axiom/test-webhooks", "description": "Test event receiver", "auth_method": "none", "max_retries": 0, "backoff_seconds": [], "enabled": false } } } } } }, "responses": { "200": { "description": "Webhook endpoint updated idempotently.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "auth_method", "max_retries", "backoff_seconds", "enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$", "description": "Assigned typed webhook-endpoint identifier.", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "description": "Tenant-scoped endpoint name." }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ] }, "max_retries": { "type": "integer" }, "backoff_seconds": { "type": "array", "items": { "type": "integer" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "additionalProperties": true } ] } } } }, "201": { "description": "Webhook endpoint registered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "auth_method", "max_retries", "backoff_seconds", "enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$", "description": "Assigned typed webhook-endpoint identifier.", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "description": "Tenant-scoped endpoint name." }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ] }, "max_retries": { "type": "integer" }, "backoff_seconds": { "type": "array", "items": { "type": "integer" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "additionalProperties": true } ] }, "example": { "data": { "id": "whe_7f8a9b0c1d234567890abcdef0123456", "name": "primary-events", "url": "https://receiver.example.com/axiom/webhooks", "description": "Primary outbound event receiver", "auth_method": "hmac_sha256", "max_retries": 3, "backoff_seconds": [ 10, 30, 60 ], "enabled": true, "created_at": "2026-03-12T12:30:00Z", "updated_at": "2026-03-12T12:30:00Z" }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/mailroom/outbox/webhook-deliveries/{delivery_id}": { "get": { "operationId": "getWebhookDeliveryStatus", "summary": "Get webhook delivery status", "description": "Returns the current status of a specific outbound webhook delivery.\n\nDelivery identifiers use the typed `whd_` wire form. The response reports\ncurrent lifecycle state, attempt count, retry budget, redacted error\nfields, correlation id, and linked intent id where available. Per-attempt\nresponse-history publication is not part of the alpha public contract.\n\nThe delivery id is stable across retry attempts for the same delivery\nrecord and is useful for receiver retry dedupe and support evidence. It\nis not a stable canonical event id. Webhook consumers must not assume\nexactly-once delivery or ordered delivery from this route.\n\n**Response format:** Canonical success envelope.\n", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "delivery_id", "in": "path", "required": true, "description": "Typed webhook delivery identifier.", "schema": { "type": "string", "pattern": "^whd_[A-Za-z0-9_-]+$", "x-axiom-identifier-shape": "typed-prefix" }, "example": "whd_8a9b0c1d2e345678901bcdef0123456" } ], "responses": { "200": { "description": "Webhook delivery status", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "delivery_id", "endpoint_id", "status", "attempt_count", "max_retries", "correlation_id", "created_at" ], "properties": { "delivery_id": { "type": "string", "pattern": "^whd_[A-Za-z0-9_-]+$", "x-axiom-identifier-shape": "typed-prefix" }, "endpoint_id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$", "description": "Target webhook endpoint", "x-axiom-identifier-shape": "typed-prefix" }, "status": { "type": "string", "enum": [ "pending", "dispatched", "delivered", "failed" ], "description": "Current delivery status.\n- pending: Queued, not yet attempted\n- dispatched: Attempted and awaiting retry or final outcome\n- delivered: Successfully delivered (2xx response)\n- failed: All retry attempts exhausted\n" }, "attempt_count": { "type": "integer", "minimum": 0, "description": "Number of dispatch attempts made so far." }, "max_retries": { "type": "integer", "minimum": 0, "description": "Configured retry attempts after the first attempt." }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled time for next retry (null if not retrying)" }, "last_error_code": { "type": "string", "description": "Last classified error code, if any." }, "last_error_message_redacted": { "type": "string", "description": "Last delivery error message with secret material redacted." }, "dispatched_at": { "type": "string", "format": "date-time", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "correlation_id": { "type": "string", "description": "Correlation identifier for the delivery workflow.", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "intent_id": { "type": "string", "nullable": true, "description": "Linked outbound intent identifier when available.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time" } } } }, "additionalProperties": true } ] }, "example": { "data": { "delivery_id": "whd_8a9b0c1d2e345678901bcdef0123456", "endpoint_id": "whe_7f8a9b0c1d234567890abcdef0123456", "status": "dispatched", "attempt_count": 1, "max_retries": 3, "next_retry_at": "2026-03-12T12:36:30Z", "last_error_code": "HTTP_503", "last_error_message_redacted": "HTTP 503", "dispatched_at": "2026-03-12T12:35:00Z", "correlation_id": "corr_01HZXAMPLE000000000000000", "intent_id": "intent_01HZXAMPLE000000000000000", "created_at": "2026-03-12T12:35:00Z" }, "status": "success" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/audit/recent": { "get": { "operationId": "getRecentAuditEntries", "summary": "Get recent audit entries", "description": "Returns recent audit log entries for the tenant, ordered by timestamp\ndescending (newest first).\n\nAudit entries record all significant actions: resource creation, updates,\ndeletions, state transitions, authentication events, and compliance checks.\n\nSupports filtering by subject type and cursor-based pagination. Legacy\nlimit/offset pagination is rejected; clients must use page[size] and\npage[after].\n", "tags": [ "Audit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of audit entries to return in this cursor page (default 10, max 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor by the previous page", "schema": { "type": "string" } }, { "name": "subject_type", "in": "query", "required": false, "description": "Filter by subject type (e.g. policy, claim, party, vendor, product).\nWhen omitted, returns entries for all subject types.\n", "schema": { "type": "string" }, "example": "policy" } ], "responses": { "200": { "description": "List of recent audit entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRecentListResponse" }, "example": { "data": [ { "id": "c8c1b574-fb94-5f72-9f6b-7ace8245889b", "action": "state_transition", "subject_type": "claim", "subject_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "actor": "claims-adjudicator@tenant.example.com", "details": { "from_state": "open", "to_state": "under_investigation", "reason": "Assigned to motor assessor for vehicle inspection" }, "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "timestamp": "2026-03-12T14:22:00Z" }, { "id": "21d38436-2690-509f-b28a-b7a4753669c4", "action": "created", "subject_type": "policy", "subject_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "actor": "onboarding-service", "details": { "product_code": "motor-comprehensive", "policy_number": "POL-US-2026-00142" }, "timestamp": "2026-03-12T14:15:00Z" } ], "status": "success", "meta": { "page_size": 10, "has_more": true, "next_cursor": "eyJwZXJmb3JtZWRfYXQiOiIyMDI2LTAzLTEyVDE0OjE1OjAwWiIsImlkIjoiYjBjMWQyZTMtZjRhNS02Nzg5LTAxMjMtNDU2Nzg5YWJjZGVmIn0" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "subject_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/roles/{roleId}": { "delete": { "operationId": "revokePartyRole", "summary": "Revoke a party role", "description": "Revoke an active role assignment from a Party. The role assignment remains\npart of the Party history and audit record; this operation changes its\nactive status rather than deleting historical evidence.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Party role assignment identifier to revoke." } ], "responses": { "200": { "description": "Party role revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleRevocationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/balance": { "get": { "operationId": "getPartyBalance", "summary": "Get a party balance", "description": "Return the ledger-derived balance for a Party, optionally scoped by\nproduct, policy, cover, category, role, and as-of time. The response is\ncomputed from runtime ledger entries and is read-only.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "product_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this product." }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this policy." }, { "name": "cover_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this cover." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit the balance to a ledger category." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit the balance to a tenant `catalogue.role_types` code." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Compute the balance as of this RFC3339 timestamp. Defaults to the current instant." }, { "name": "decompose", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include balance computation explanation details when true." } ], "responses": { "200": { "description": "Party balance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyBalanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "product_id", "policy_id", "cover_id", "category", "role", "decompose" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/me/tenants": { "get": { "operationId": "getMeTenants", "tags": [ "Identity" ], "summary": "List admitted tenants", "description": "Returns the tenants admitted for the authenticated actor. Use the returned tenant selection data to request a server-minted tenant context.", "responses": { "200": { "description": "Admitted tenant list for the authenticated actor.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "granting_role" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Tenant identifier admitted for this authenticated actor.", "example": "tnt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Tenant display name.", "example": "Example Tenant" }, "granting_role": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Role granting access to the tenant.", "example": "tenant_operator" } } } }, "meta": { "type": "object", "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of admitted tenants returned." } } } }, "additionalProperties": true } ] } } } }, "401": { "description": "Bearer token missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "No tenant admission is available for this actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "bootstrap-not-required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "admitted-tenant-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "bootstrap-read", "tenant_context": "bootstrap-not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/me/tenant-context": { "post": { "operationId": "postMeTenantContext", "tags": [ "Identity" ], "summary": "Mint tenant context", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tenant_id" ], "properties": { "tenant_id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Tenant identifier selected from GET /v1/me/tenants.", "example": "tnt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "x-axiom-identifier-shape": "typed-prefix" } } } } } }, "responses": { "200": { "description": "Tenant context minted for an admitted tenant.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "tenant_context_token", "tenant_id", "expires_at" ], "properties": { "tenant_context_token": { "type": "string", "minLength": 1, "description": "Server-minted token for X-Tenant-Context on tenant-scoped requests.", "example": "" }, "tenant_id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Tenant identifier bound into the token.", "example": "tnt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "x-axiom-identifier-shape": "typed-prefix" }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC expiry timestamp.", "example": "2026-08-10T12:00:00Z" } } } }, "additionalProperties": true } ] } } } }, "400": { "description": "Tenant selection payload is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer token missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The selected tenant is not admitted for this actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "bootstrap-not-required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "admitted-tenant-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.22 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "bootstrap-mint-restricted", "tenant_context": "bootstrap-not-required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "parameters": { "CatalogueRefPath": { "name": "catalogue-ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Logical catalogue identifier (slug, e.g. `icd-10-za`)." }, "CatalogueRelationshipRefPath": { "name": "catalogue-ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Logical catalogue identifier (e.g. `icd-10-za`)." }, "CorrelationHeader": { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Correlation id for request tracing." }, "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for end-to-end tracing.\nIf not provided, the server generates one automatically.\nThe response always includes this header for support reference.\n", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "example": "req-abc-123-def-456" }, "ReplacementIdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Replacement workflow identifier (prp_ typed-prefix).", "example": "prp_01j1234567890abcdefghijk" }, "TenantHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)." }, "TenantIdHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "description": "Server-minted tenant-context token (TCT) in request header.\n\n**Required** for all tenant-scoped requests. Obtain it from\n`POST /v1/me/tenant-context` after discovering accessible tenants via\n`GET /v1/me/tenants`. The TCT is a short-lived HMAC-signed token that\ncarries the selected tenant and the authenticated account subject; the\nclient-supplied tenant selectors are not accepted.\n\nThe API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.\n", "schema": { "type": "string" }, "example": "" } }, "schemas": { "ActivateProductRequest": { "type": "object", "required": [ "activated_by" ], "properties": { "activated_by": { "type": "string", "description": "Identifier of the user or service activating the product", "example": "usr_3f8a" } }, "additionalProperties": false }, "AddBusinessRuleRequest": { "type": "object", "required": [ "code", "name", "rule_type", "expression", "priority" ], "properties": { "code": { "type": "string", "description": "Machine-readable rule code (must be unique within the ruleset)", "example": "max-sum-insured", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable rule name", "example": "Maximum Sum Insured Limit" }, "rule_type": { "type": "string", "enum": [ "validation", "calculation", "condition", "action", "commission_rate", "commission_split", "group_discount", "discount_composition" ], "description": "Classification of the rule's purpose", "example": "validation" }, "expression": { "type": "string", "description": "CEL expression for rule evaluation. Both complex expressions\n(e.g., \"cover.sum_insured <= 50000000\") and bare literals\n(e.g., \"25000\") are valid CEL.\n", "example": "25000" }, "description": { "type": "string", "nullable": true, "description": "Human-readable explanation of the rule", "example": "Sum insured must not exceed KES 50,000,000 for standard home contents policies" }, "priority": { "type": "integer", "description": "Execution priority (lower executes first)", "example": 20 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional rule metadata", "example": { "regulatory_ref": "IRA-KE-2025-HC-7" } }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "Structured conditions evaluated before the expression" }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" }, "description": "Actions to execute when the rule evaluates to true" } }, "additionalProperties": false }, "AddCoverItemRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "example": "gp-consultation", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "example": "GP Consultation" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Catalogue-driven cover-item kind code (e.g. benefit, peril).", "example": "benefit", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "classification": { "type": "string" }, "triggers": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/AddCoverTermRequest" } } }, "additionalProperties": false }, "AddCoverRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "description": "Short code for this coverage section", "example": "TPL-BODILY", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Third-Party Bodily Injury" }, "description": { "type": "string", "description": "Detailed description of coverage", "example": "Covers liability for bodily injury to third parties arising from vehicle use" }, "type": { "type": "string", "enum": [ "basic", "optional", "rider" ], "description": "Coverage type within the product", "example": "basic" }, "sum_insured": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 100000000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "deductible": { "type": "integer", "format": "int64", "nullable": true, "description": "Excess amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 50000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "cover_items": { "type": "array", "nullable": true, "description": "CRS-3: nested cover items, each with its own terms. Persisted as the full\ncanonical cover.* row graph in one atomic transaction.\n", "items": { "$ref": "#/components/schemas/AddCoverItemRequest" } }, "cover_terms": { "type": "array", "nullable": true, "description": "CRS-3: nested cover-level terms (conditions, limits, exclusions).", "items": { "$ref": "#/components/schemas/AddCoverTermRequest" } } }, "additionalProperties": false }, "AddCoverTermRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "example": "annual-limit", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "example": "Annual Limit" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Term type (condition | limit | exclusion | excess).", "example": "limit", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "expression": { "type": "string", "description": "Rule expression for the term (rules-as-data)." }, "boundary": { "$ref": "#/components/schemas/HierarchyTermBoundary" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true } }, "additionalProperties": false }, "AddPartyGroupMemberRequest": { "type": "object", "description": "Exactly one of party_id or group_id must be supplied. Passing neither\nor both is rejected with 400. fail-loud.\n", "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "group_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time", "description": "Defaults to now() server-side when omitted" } }, "additionalProperties": false }, "ArchiveIngestResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/archiveObjectDTO" } }, "required": [ "data" ], "additionalProperties": true } ] }, "AssembleEvidencePackRequest": { "type": "object", "required": [ "name", "record_ids" ], "properties": { "name": { "type": "string", "description": "Descriptive name for the evidence pack", "example": "Policy POL-2026-00089 \u2014 Underwriting Evidence Pack" }, "record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of evidence record IDs to include in the pack", "example": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237" ] }, "assembled_by": { "type": "string", "description": "Identifier of the user or service assembling the pack", "example": "underwriting-service" } }, "additionalProperties": false }, "Assertion": { "type": "object", "required": [ "id", "logical_assertion_id", "event_id", "cover_id", "rule_version_id", "label_logical_entry_id", "status", "payload", "valid_from", "asserted_from", "recorded_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Per-row physical identity (the row UUID)", "readOnly": true, "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "logical_assertion_id": { "type": "string", "format": "uuid", "description": "Deterministic UUIDv5 logical-thread identity over\n(tenant context, event_id, cover_id, rule_version_id). All rows sharing this\nvalue are versions of the same conceptual assertion.\n", "readOnly": true, "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "event_id": { "type": "string", "description": "Reference to the Event this assertion responds to", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_id": { "type": "string", "description": "Reference to the Cover the assertion is determined under", "example": "cov_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_version_id": { "type": "string", "description": "The rule-engine version that produced this assertion\n(deterministic reproducibility under the governed contract).\n", "example": "rv_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "label_logical_entry_id": { "type": "string", "format": "uuid", "description": "FK to catalogue.entries(logical_entry_id) \u2014 the sector label key\n(claim / loss / cession / trigger_event / notification). Surfaced raw;\nthe tenant display label facade is a named later slice.\n", "example": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "x-axiom-identifier-shape": "uuid" }, "status": { "type": "string", "enum": [ "pending", "settled", "reopened", "adjusted", "finalised" ], "description": "Contract-response lifecycle status (separate from the asserted_* axis)", "example": "settled" }, "payload": { "type": "object", "additionalProperties": true, "description": "Per-event contract-response payload (decision, remarks, etc.) \u2014 domain-specific shape" }, "amount_minor": { "type": "integer", "format": "int64", "nullable": true, "description": "Assessed amount in exact integer minor units (the governed contract); the\nmoney the settling payment binds to. NULL until the decision is terminal.\n", "example": 8000000 }, "currency_code": { "type": "string", "nullable": true, "description": "Lowercase ISO-4217 currency for amount_minor (the governed contract). NULL until terminal.", "example": "zar", "x-axiom-coded-value-classification": "iso-4217-currency-code" }, "ledger_transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "FK to the ledger transaction that records this assertion's outcome. NULL until posted.", "example": "32798e17-3851-562c-b192-f49109f3465d", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time", "description": "Real-world validity start (when the contract response is in force)", "example": "2026-03-08T16:00:00Z" }, "valid_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Real-world validity end (open when unset)", "example": null }, "asserted_from": { "type": "string", "format": "date-time", "description": "Belief-axis start \u2014 when the engine held this belief (Snodgrass assertion-time)", "example": "2026-03-08T16:00:00Z" }, "asserted_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Belief-axis end (open when this is the current belief)", "example": null }, "recorded_at": { "type": "string", "format": "date-time", "description": "Immutable physical anchor \u2014 the moment this row was written", "readOnly": true, "example": "2026-03-08T16:00:01Z" } }, "x-axiom-money-classification": "flattened-runtime-money-wire-shape", "x-axiom-money-currency-association": "inline-currency-code-property", "x-axiom-money-migration-target": "#/components/schemas/Money", "additionalProperties": false }, "AssertionListResponse": { "type": "object", "required": [ "data", "meta", "status" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Assertion" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "AssertionResponse": { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "$ref": "#/components/schemas/Assertion" }, "status": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" } }, "additionalProperties": false }, "AssessClaimRequest": { "type": "object", "required": [ "assessed_by", "assessment_notes" ], "properties": { "assessed_by": { "type": "string", "description": "Identifier of the assessor performing the assessment", "example": "assessor-jvd-001" }, "assessment_notes": { "type": "string", "description": "Detailed notes from the assessment", "example": "Site inspection completed. Damage consistent with reported cause. Recommended approval less policy excess of R5,000." }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Approved claim amount. Null if recommending denial.", "nullable": true, "additionalProperties": true }, "item_assessments": { "type": "array", "nullable": true, "description": "Per-item assessment details", "items": { "$ref": "#/components/schemas/ItemAssessment" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata for the assessment", "example": { "inspection_date": "2026-03-05", "photos_attached": 12 } } }, "additionalProperties": false }, "AssessClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimAssessment" }, "assessment": { "type": "array", "description": "Rule evaluation results from tenant-specific adjudication", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": true } ] }, "AssignGroupRoleRequest": { "type": "object", "required": [ "role_type", "context" ], "properties": { "role_type": { "type": "string", "enum": [ "sponsor", "provider", "beneficiary", "accepted_provider_network" ], "example": "accepted_provider_network" }, "context": { "type": "object", "required": [ "entity_type", "entity_id" ], "properties": { "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item" ], "example": "product" }, "entity_id": { "type": "string", "example": "CM-MED-01", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "effective_from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AuditRecentEntry": { "type": "object", "required": [ "id", "action", "subject_type", "subject_id", "actor", "timestamp" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Audit entry identifier", "x-axiom-identifier-shape": "uuid" }, "action": { "type": "string", "description": "Action performed. Common values include created, updated, deleted,\nstate_transition, login, evaluation, and approval.\n", "example": "state_transition" }, "subject_type": { "type": "string", "description": "Type of the entity acted upon", "example": "claim" }, "subject_id": { "type": "string", "description": "Identifier of the entity acted upon", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor": { "type": "string", "description": "Identifier of the user or service that performed the action.", "example": "claims-adjudicator@tenant.example.com" }, "details": { "type": "object", "additionalProperties": true, "description": "Action-specific details. For state_transition, includes from_state and\nto_state. For updates, includes changed fields.\n", "example": { "from_state": "open", "to_state": "under_investigation", "reason": "Assigned to assessor for inspection" } }, "correlation_id": { "type": "string", "format": "uuid", "description": "Request correlation ID for tracing", "x-axiom-identifier-shape": "uuid" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the action occurred", "example": "2026-03-12T14:22:00Z" } }, "additionalProperties": false }, "AuditRecentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRecentEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "AuthorisationTransition": { "type": "object", "required": [ "id", "logical_authorisation_id", "entity_type", "entity_id", "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id", "valid_from", "asserted_from" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "logical_authorisation_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "entity_type": { "type": "string", "enum": [ "claim" ] }, "entity_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string" }, "authorisation_kind": { "type": "string" }, "authorising_actor": { "type": "string", "format": "uuid" }, "authorised_scope": { "type": "object", "additionalProperties": true }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "nullable": true }, "governing_version_kind": { "type": "string", "nullable": true }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true }, "compliance_outcome": { "type": "string", "nullable": true }, "compliance_list_version": { "type": "string", "nullable": true }, "compliance_list_authority": { "type": "string", "nullable": true }, "decision_date": { "type": "string", "format": "date-time" }, "explanation_node_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true }, "valid_from": { "type": "string", "format": "date-time" }, "asserted_from": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "BalanceExplanation": { "type": "object", "required": [ "inputs", "rule_version", "computation", "entry_ids" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Input facts used for the balance computation. Supports explainability\nby recording the exact parameters that produced this result.\n", "example": { "account_code": "PREM-RCV-001", "date_from": "2026-01-01T00:00:00Z", "date_to": "2026-03-10T23:59:59Z", "include_pending": false } }, "rule_version": { "type": "string", "description": "Version identifier of the balance computation rule applied (as-was semantics)", "example": "balance-calc-v2.1.0" }, "computation": { "type": "string", "description": "Human-readable description of the computation method", "example": "Sum of posted credits minus posted debits for account PREM-RCV-001" }, "entry_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of ledger entry IDs included in this balance calculation", "example": [ "50447be1-27bd-5a7a-b51c-edce72303e3f", "ba8f3ab8-3beb-55dc-874f-040a4f50529a" ] } }, "additionalProperties": false }, "BalanceResult": { "type": "object", "required": [ "account_code", "as_of", "currency", "amount", "entry_count", "explanation" ], "properties": { "account_code": { "type": "string", "description": "Account code for which the balance was computed", "example": "PREM-RCV-001" }, "as_of": { "type": "string", "format": "date-time", "description": "Point-in-time at which the balance was computed", "example": "2026-03-10T23:59:59Z" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "USD" }, "amount": { "type": "integer", "format": "int64", "description": "Net balance amount (debits minus credits) as of the specified timestamp in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 4525075, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "entry_count": { "type": "integer", "description": "Number of ledger entries included in the balance computation", "example": 128 }, "explanation": { "$ref": "#/components/schemas/BalanceExplanation" } }, "additionalProperties": false }, "BalanceResultResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "BindQuoteRequest": { "type": "object", "required": [ "payment_method", "bound_by" ], "properties": { "payment_method": { "type": "string" }, "bound_by": { "type": "string" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Bind-time parties (must match quote snapshot if provided)" } }, "additionalProperties": false }, "BindQuoteResult": { "type": "object", "required": [ "quote_id" ], "description": "Result of a successful quote bind operation", "properties": { "quote_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_id": { "type": "string", "description": "Created policy ID (optional, may be absent in multi-product binds)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Created policy IDs for multi-product binds" }, "premium_ids": { "type": "array", "items": { "type": "string" }, "description": "Created premium record IDs" }, "allocation_explanation_tree_id": { "type": "string", "description": "Explanation tree for premium allocation.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" }, "description": "Created ledger entry IDs" } }, "additionalProperties": false }, "BindQuoteResultResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BindQuoteResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "BusinessRule": { "type": "object", "required": [ "id", "rule_id", "code", "name", "rule_type", "expression", "priority", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique identifier for this rule instance within the ruleset", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "x-axiom-identifier-shape": "uuid" }, "rule_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Canonical rule identifier (shared across versions)", "example": "c89309e9-11d4-5c80-95cc-5bc9b4b9857c", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Machine-readable rule code for cross-referencing", "example": "min-driver-age", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable rule name", "example": "Minimum Driver Age Eligibility" }, "rule_type": { "type": "string", "enum": [ "validation", "calculation", "condition", "action", "commission_rate", "commission_split", "group_discount", "discount_composition" ], "description": "Classification of the rule's purpose.\n- validation: Checks data correctness and completeness\n- calculation: Computes a derived value\n- condition: Controls conditional evaluation\n- action: Produces an action result\n- commission_rate: Computes a commission rate\n- commission_split: Computes a commission split\n- group_discount: Computes a group discount\n- discount_composition: Composes discount rules\n", "example": "validation" }, "expression": { "type": "string", "description": "CEL (Common Expression Language) expression that evaluates this rule.\nMust be deterministic and side-effect free.\n", "example": "applicant.age >= 18 && applicant.age <= 75" }, "description": { "type": "string", "nullable": true, "description": "Human-readable explanation of what this rule does and why", "example": "Drivers must be between 18 and 75 years old for standard motor cover" }, "priority": { "type": "integer", "description": "Execution priority within the ruleset. Lower numbers execute first.\nRules with the same priority may execute in any order.\n", "example": 10 }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Lifecycle status of this individual rule.\n- draft: Under development\n- active: Available for evaluation\n- deprecated: No longer evaluated in new transactions\n", "example": "active" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible metadata for the rule (e.g. regulatory reference, risk category)", "example": { "regulatory_ref": "FSCA-PPR-2018-S4.3", "risk_category": "driver_eligibility" } }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "Structured conditions evaluated before the main expression" }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" }, "description": "Actions to execute when the rule evaluates to true" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\"). Each\nentry explains one element of the rule (e.g. a CEL term) for a human reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated (e.g. a CEL term, a limit, a value_type)." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when this rule was created", "example": "2026-01-10T08:30:00Z" } }, "additionalProperties": false }, "BusinessRuleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessRule" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CatalogueRelationship": { "type": "object", "required": [ "id", "source_catalogue", "source_code", "target_catalogue", "target_code", "relationship_type", "scope", "effective_from" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "crl_01ARZ3NDEKTSV4RRFFQ69G5FAV", "x-axiom-identifier-shape": "typed-prefix" }, "source_catalogue": { "type": "string" }, "source_code": { "type": "string" }, "target_catalogue": { "type": "string" }, "target_code": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "parent_of", "maps_to", "member_of", "qualifies", "excludes", "bundles_with", "supersedes", "interacts_with" ] }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true }, "scope": { "type": "string", "enum": [ "universal", "jurisdiction", "tenant" ] }, "jurisdiction": { "type": "string", "nullable": true }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "CatalogueRelationshipBody": { "type": "object", "required": [ "target_catalogue", "target_code", "relationship_type", "scope", "effective_from" ], "properties": { "source_catalogue": { "type": "string", "description": "Optional on the single-create endpoint (defaults from\n:catalogue-ref). REQUIRED on the batch endpoint. When set,\nMUST equal the path value \u2014 silent override is forbidden.\n" }, "source_code": { "type": "string", "description": "Optional on the single-create endpoint (defaults from\n:code). REQUIRED on the batch endpoint when source_catalogue\nis set.\n" }, "target_catalogue": { "type": "string" }, "target_code": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "parent_of", "maps_to", "member_of", "qualifies", "excludes", "bundles_with", "supersedes", "interacts_with" ] }, "attributes": { "type": "object", "additionalProperties": true }, "scope": { "type": "string", "enum": [ "universal", "jurisdiction", "tenant" ] }, "jurisdiction": { "type": "string", "description": "Required when scope=jurisdiction." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "CertificateProjection": { "type": "object", "required": [ "policy_id", "party_id", "version_id", "roles", "effective_from" ], "properties": { "policy_id": { "type": "string", "description": "Typed-prefix policy identifier (pol_\u2026)", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "party_id": { "type": "string", "description": "Identifier of the member party", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "version_id": { "type": "string", "description": "Typed-prefix policy-version identifier (pov_\u2026) at as_of time", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Active role names for this member at as_of time" }, "effective_from": { "type": "string", "format": "date-time", "description": "When this member's coverage became effective" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "When this member's coverage ends (null = currently active)" } }, "additionalProperties": false }, "CertificateResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CertificateProjection" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Claim": { "type": "object", "required": [ "id", "claim_number", "event_id", "policy_id", "status", "primary_party_id", "event_date", "reported_date", "total_claimed_amount", "description", "priority", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim identifier", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "claim_number": { "type": "string", "description": "Human-readable claim reference number", "readOnly": true, "example": "CLM-2026-00042" }, "event_id": { "type": "string", "format": "uuid", "description": "Reference to the insured event that triggered this claim", "example": "4cbb0168-4d04-535d-969b-927f53d9c96c", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy under which this claim is made", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "status": { "$ref": "#/components/schemas/ClaimStatus" }, "primary_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the primary claimant party", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" }, "event_date": { "type": "string", "format": "date-time", "description": "Date and time when the insured event occurred", "example": "2026-02-15T14:30:00Z" }, "reported_date": { "type": "string", "format": "date-time", "description": "Date and time when the claim was reported", "example": "2026-02-16T09:00:00Z" }, "total_claimed_amount": { "type": "integer", "format": "int64", "readOnly": true, "deprecated": true, "description": "Derived, read-only compatibility field. Equal to SUM(claim_items.claimed_amount). No longer stored as a stored field (governed contract). Amount in the smallest currency unit (e.g. cents). Exact integer representation.\n", "example": 4500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "description": { "type": "string", "description": "Free-text description of the claim circumstances", "example": "Rear-end collision at intersection of Main St and 5th Ave. Third-party vehicle damage and whiplash injury to driver." }, "priority": { "$ref": "#/components/schemas/ClaimPriority" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for tenant-specific claim data", "example": { "loss_location": "London, Greater London", "police_report_number": "MET-2026-LDN-3321", "weather_conditions": "clear" } }, "claim_items": { "type": "array", "nullable": true, "description": "Individual line items making up this claim", "items": { "$ref": "#/components/schemas/ClaimItem" } }, "fraud_score": { "type": "string", "nullable": true, "readOnly": true, "description": "Fraud detection score as exact decimal string in [0, 1]. Null when fraud scoring has not been evaluated for this claim. Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0.25" }, "fraud_status": { "type": "string", "readOnly": true, "enum": [ "not_evaluated", "clear", "suspicious", "confirmed_fraud" ], "description": "Fraud evaluation status. Closed enum \u2014 no other values are valid. Legacy value \"fraudulent\" is a compatibility alias for ingest only; API responses always use \"confirmed_fraud\".\n", "example": "not_evaluated" }, "requires_investigation": { "type": "boolean", "readOnly": true, "description": "Derived from fraud_score >= investigation_threshold. False when fraud scoring has not been evaluated.\n", "example": false }, "is_subrogated": { "type": "boolean", "description": "Whether this claim involves subrogation against a third party.", "example": false }, "subrogation_status": { "type": "string", "readOnly": true, "enum": [ "not_identified", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Subrogation lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_identified" }, "recovery_status": { "type": "string", "readOnly": true, "enum": [ "none", "pending", "partial", "completed", "abandoned" ], "description": "Recovery lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "none" }, "assessments": { "type": "array", "nullable": true, "description": "Assessment records for this claim", "items": { "$ref": "#/components/schemas/ClaimAssessment" } }, "payments": { "type": "array", "nullable": true, "description": "Payment records for this claim", "items": { "$ref": "#/components/schemas/ClaimPayment" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was last updated", "readOnly": true, "example": "2026-02-20T11:30:00Z" } }, "additionalProperties": false }, "ClaimAssessment": { "type": "object", "required": [ "id", "claim_id", "assessment_type", "assessed_by", "assessed_at", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique assessment identifier", "readOnly": true, "example": "cla_01j9zxkp8wqrm2n4v6t5s3d7f6", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the assessed claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "assessment_type": { "type": "string", "description": "Type of assessment performed (e.g. initial, supplementary, independent, medical)", "example": "initial" }, "assessed_by": { "type": "string", "description": "Identifier of the assessor (user ID or external reference)", "example": "assessor-jvd-001" }, "assessed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the assessment was completed", "example": "2026-02-18T16:00:00Z" }, "status": { "type": "string", "enum": [ "approved", "denied", "partial" ], "description": "Assessment outcome status:\n- `approved`: Full claim amount approved\n- `denied`: Claim denied \u2014 no amount approved\n- `partial`: Partial amount approved \u2014 less than total claimed\n", "example": "approved" }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Total amount approved by this assessment. Null if denied.", "nullable": true, "additionalProperties": true }, "denial_reason": { "type": "string", "nullable": true, "description": "Reason for denial or partial denial (null if approved)", "example": null }, "notes": { "type": "string", "nullable": true, "description": "Free-text assessor notes", "example": "All claimed items verified against repair quotations. Approved less R3,000 excess." }, "rule_results": { "type": "array", "nullable": true, "description": "Results from automated rule evaluations during assessment", "items": { "$ref": "#/components/schemas/RuleEvaluationResult" } } }, "additionalProperties": false }, "ClaimItem": { "type": "object", "required": [ "id", "claim_id", "item_type", "description", "claimed_amount", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim item identifier", "readOnly": true, "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the parent claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "item_type": { "type": "string", "description": "Category of the claim item (e.g. vehicle_damage, medical, property, liability)", "example": "vehicle_damage" }, "description": { "type": "string", "description": "Detailed description of the claimed item", "example": "Rear bumper replacement and respray \u2014 2024 Toyota Corolla" }, "claimed_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount claimed for this item (exact integer minor units + lowercase ISO-4217 currency code)." }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount approved by assessor. Null if not yet assessed.", "nullable": true, "additionalProperties": true }, "paid_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount actually paid for this item. Null if not yet paid.", "nullable": true, "additionalProperties": true }, "service_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date when the service or repair was performed", "example": "2026-03-01T08:00:00Z" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for this claim item", "example": { "repair_shop": "Cape Auto Body", "part_numbers": [ "TB-2024-RR-01", "PS-2024-FW-03" ] } }, "status": { "type": "string", "description": "Current status of this claim item", "example": "approved", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "salvage_status": { "type": "string", "readOnly": true, "enum": [ "not_applicable", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Salvage lifecycle status for this claim item. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_applicable" }, "salvage_amount": { "type": "string", "readOnly": true, "description": "Salvage recovery amount as exact decimal string in the smallest currency unit (e.g. cents). Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim item was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" } }, "additionalProperties": false }, "ClaimListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ClaimPayment": { "type": "object", "required": [ "id", "claim_id", "payment_id", "amount_paid", "payment_method", "processed_at", "processed_by", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim payment identifier", "readOnly": true, "example": "cpy_01j9zxkp8wqrm2n4v6t5s3d7f7", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the parent claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "payment_id": { "type": "string", "format": "uuid", "description": "Reference to the payment record in the billing system", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" }, "amount_paid": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount disbursed in this payment (exact integer minor units + lowercase ISO-4217 currency code)." }, "payment_method": { "type": "string", "description": "Method used for payment disbursement", "example": "bank_transfer" }, "processed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was processed", "example": "2026-02-25T10:00:00Z" }, "processed_by": { "type": "string", "description": "Identifier of the user or system that processed the payment", "example": "payments-officer-mk-003" }, "status": { "type": "string", "description": "Current payment status", "example": "completed", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "governed contract authorisation row cited by this payment, when present.", "example": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "x-axiom-identifier-shape": "uuid" }, "authorisation_gate_outcome": { "type": "string", "nullable": true, "description": "Outcome returned by the authorisation payment gate for a cited authorisation.", "enum": [ "clear", "override", "not-applicable" ], "example": "clear" } }, "additionalProperties": false }, "ClaimPriority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "description": "Claim priority level:\n- `low` \u2014 Routine claim, standard handling priority (e.g. minor property damage)\n- `medium` \u2014 Standard claim requiring timely processing (e.g. motor accident)\n- `high` \u2014 Significant claim requiring expedited handling (e.g. business interruption)\n- `urgent` \u2014 Critical claim requiring immediate attention (e.g. hospitalisation, total loss)\n", "example": "medium" }, "ClaimReserve": { "type": "object", "required": [ "id", "claim_id", "policy_id", "reserve_type", "initial_amount", "current_amount", "released_amount", "is_active", "state", "operation", "established_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "claim_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "reserve_type": { "type": "string" }, "initial_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "current_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "released_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "is_active": { "type": "boolean" }, "state": { "type": "string", "enum": [ "active", "partially_released", "fully_released", "inactive_cancelled" ] }, "reason": { "type": "string" }, "operation": { "type": "string" }, "predecessor_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "successor_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "established_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ClaimStatus": { "type": "string", "enum": [ "submitted", "under_review", "assessed", "partial_approval", "denied", "paid", "closed" ], "description": "Claim entity lifecycle status. The claim lifecycle follows this state machine:\n\n```\nsubmitted -> under_review -> assessed ---------> paid -> closed\n +-> partial_approval -> paid -> closed\n +-> denied ----------------------> closed\n```\n\nTransitions:\n- `submitted` -> `under_review`: Claim enters active review and triage\n- `under_review` -> `assessed`: Full approval \u2014 assessment approves total claimed amount\n- `under_review` -> `partial_approval`: Partial approval \u2014 approved amount is less than claimed\n- `under_review` -> `denied`: Claim denied \u2014 no amount approved\n- `assessed` -> `paid`: Payment disbursed for fully approved claim\n- `partial_approval` -> `paid`: Payment disbursed for partially approved claim\n- `paid` -> `closed`: Claim lifecycle complete after payment\n- `denied` -> `closed`: Claim lifecycle complete after denial\n\nNote: The assessment outcome (approved, denied, partial) is recorded on\n`ClaimAssessment.status`, not on `Claim.status`. The claim entity status\nreflects the overall lifecycle position.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nPer-value descriptions:\n- `submitted`: Claim has been filed and is awaiting initial review\n- `under_review`: Claim is under active assessment by an assessor\n- `assessed`: Assessment complete with full approval; claim is payable\n- `partial_approval`: Assessment complete with partial approval; claim is payable for the approved amount\n- `denied`: Claim has been denied following assessment; no payment will be made\n- `paid`: Payment has been disbursed to the claimant\n- `closed`: Claim lifecycle is complete (paid, denied, or otherwise resolved)\n", "example": "submitted" }, "Commission": { "type": "object", "required": [ "id", "role_type", "commission_type", "rate", "calculation_basis", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique commission structure identifier", "example": "fa590161-dad2-5a57-84d1-4a71d6457a36", "x-axiom-identifier-shape": "uuid" }, "role_type": { "type": "string", "description": "The intermediary role this commission applies to (e.g. broker, agent)", "example": "broker" }, "commission_type": { "type": "string", "description": "Type of commission (e.g. initial, renewal, override)", "example": "initial" }, "rate": { "type": "number", "format": "double", "description": "Commission rate (as a decimal, e.g. 0.10 for 10%)", "example": 0.1 }, "min_amount": { "type": "integer", "format": "int64", "nullable": true, "description": "Minimum commission amount per transaction in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 5000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "max_amount": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum commission amount per transaction in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "calculation_basis": { "type": "string", "description": "What the commission rate is applied to (e.g. gross_premium, net_premium)", "example": "gross_premium" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this commission structure is currently active", "example": "active" } }, "additionalProperties": false }, "ComplianceReport": { "type": "object", "required": [ "evaluation_id", "generated_at", "compliance_assertion", "findings", "explanation_tree_id" ], "properties": { "evaluation_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "compliance_assertion": { "type": "boolean", "description": "Always false under the governed contract \u2014 reports are evidence-enabling, not compliance-asserting" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/JurisdictionFinding" } }, "ruleset_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PackVersionRef" } }, "explanation_tree_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "ComplianceReportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ComplianceReport" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ContactInfo": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$", "description": "Phone number in E.164 format" }, "preferred_contact_method": { "type": "string", "enum": [ "email", "phone", "mail" ], "description": "Preferred contact method" } }, "additionalProperties": false }, "CorrectionEnvelopeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CorrectionResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CorrectionRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "x-axiom-identifier-shape": "typed-prefix" }, "recovery_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "correction_type": { "type": "string", "enum": [ "full_reversal", "partial_reversal", "write_off" ] }, "amount": { "type": "string", "nullable": true, "description": "String-encoded exact decimal in smallest currency unit (governed contract)", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "effective_at": { "type": "string", "format": "date-time" }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "CorrectionResponse": { "type": "object", "properties": { "correction": { "$ref": "#/components/schemas/CorrectionRecord" }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "Cover": { "type": "object", "required": [ "id", "code", "name", "type", "sum_insured", "deductible", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique cover identifier", "example": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code identifying this coverage section", "example": "INPATIENT", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name of the coverage section", "example": "Inpatient Hospital Cover" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of what this cover provides", "example": "Covers hospitalisation, surgery, and intensive care unit stays" }, "type": { "type": "string", "enum": [ "basic", "optional", "rider" ], "description": "Coverage type within the product.\n- basic: Core coverage included by default\n- optional: Coverage that can be added at the policyholder's discretion\n- rider: Supplementary coverage attached to a base cover\n", "example": "basic" }, "sum_insured": { "type": "integer", "format": "int64", "description": "Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 50000000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "deductible": { "type": "integer", "format": "int64", "description": "Amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 100000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for cover-specific configuration", "example": { "waiting_period_days": 30, "co_payment_percentage": 20 } }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this cover is currently active within the product", "example": "active" }, "cover_items": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CoverItem" }, "description": "Cover provisions (benefits or perils) associated with this cover" }, "cover_terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/HierarchyTerm" }, "description": "Terms (conditions, limits, exclusions) specific to this cover" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\") explaining\nthe cover for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "CoverItem": { "type": "object", "required": [ "id", "code", "name", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique cover provision identifier", "example": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this cover provision", "example": "SURG-BEN", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Surgical Benefit" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the cover provision", "example": "Covers elective and emergency surgical procedures" }, "type": { "type": "string", "enum": [ "benefit", "peril" ], "description": "Sector-vernacular discriminator for this cover provision (per the governed contract).\n- benefit: medical-aid / life vernacular for a positive entitlement under the cover\n- peril: short-term / property vernacular for a risk event that triggers the cover\n", "example": "benefit" }, "classification": { "type": "string", "nullable": true, "description": "Optional classification or grouping for the cover provision", "example": "medical" }, "triggers": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Event types or conditions that trigger this cover provision", "example": [ "hospitalisation", "day_surgery" ] }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/HierarchyTerm" }, "description": "Terms specific to this cover provision" } }, "additionalProperties": false }, "CoverListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cover" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "CoverResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cover" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CreateCorrectionRequest": { "type": "object", "required": [ "correction_type", "reason", "evidence_refs", "effective_at" ], "properties": { "correction_type": { "type": "string", "enum": [ "full_reversal", "partial_reversal", "write_off" ], "description": "Type of correction. Closed enum. `full_reversal`: reverses the full original amount. `partial_reversal`: reverses a specified portion. `write_off`: writes off a specified or full amount.\n", "example": "full_reversal" }, "amount": { "type": "string", "nullable": true, "pattern": "^[1-9]\\d*$", "description": "Required for `partial_reversal`, forbidden for `full_reversal`, optional for `write_off`. String-encoded exact decimal in smallest currency unit (e.g. cents). No float (governed contract).\n", "example": "2500000", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string", "description": "Reason for the correction", "example": "Recovery recorded in error \u2014 settlement rescinded" }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Non-empty array of evidence references supporting this correction", "example": [ "ev-rescission-notice-001" ] }, "effective_at": { "type": "string", "format": "date-time", "description": "When the correction is effective (RFC 3339)", "example": "2026-03-18T14:00:00Z" } }, "additionalProperties": false }, "CreateEvidenceRecordRequest": { "type": "object", "required": [ "record_type", "subject_type", "subject_id", "content" ], "properties": { "record_type": { "type": "string", "description": "Classification of the evidence record", "example": "rule_evaluation" }, "subject_type": { "type": "string", "description": "Type of the entity this evidence pertains to", "example": "policy" }, "subject_id": { "type": "string", "description": "Identifier of the subject entity", "example": "e316666f-e293-5ccc-81a8-8a12fe4094c5", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content": { "type": "object", "additionalProperties": true, "description": "Structured evidence payload", "example": { "evaluation": "premium_calculation", "inputs": { "vehicle_value": 450000, "driver_age": 32, "claims_history": 0 }, "rule_version": "motor-pricing-v2.0.1", "base_premium": 8100, "loadings": [], "discounts": [ { "type": "no_claims_bonus", "percentage": 0.2 } ], "final_premium": 6480 } }, "created_by": { "type": "string", "description": "Identifier of the creating user or service", "example": "pricing-engine" } }, "additionalProperties": false }, "CreateEvidenceRecordResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedEvidenceRecordResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CreateIntegrationInput": { "type": "object", "required": [ "system_name", "data_categories", "data_direction", "transfer_method" ], "properties": { "system_name": { "type": "string", "description": "Name of the external system", "example": "MediCheck Claims API" }, "data_categories": { "type": "array", "items": { "type": "string" }, "description": "Categories of data exchanged", "example": [ "health_records", "claim_documents" ] }, "data_direction": { "type": "string", "enum": [ "ingress", "egress", "bidirectional" ], "description": "Direction of data flow relative to Axiom", "example": "ingress" }, "transfer_method": { "type": "string", "description": "Technical method for data transfer", "example": "rest_api" } }, "additionalProperties": false }, "CreatePartyGroupRequest": { "type": "object", "required": [ "display_name" ], "properties": { "group_type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "Defaults to static when omitted" }, "display_name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "external_id": { "type": "string", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "id_namespace": { "type": "string", "default": "tenant" }, "membership_rule_id": { "type": "string", "description": "Required when group_type = dynamic", "example": "rule-party-age-over-18", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "CreatePartyRequest": { "type": "object", "required": [ "party_type", "attributes" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Optional client-provided identifier. If omitted, the server generates one.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "party_type": { "type": "string", "enum": [ "individual", "organization", "system" ], "description": "Identity classification of the party. Contextual participation such as broker, provider, agent, adjuster, or assessor belongs to PartyRole.role_type.", "example": "individual" }, "external_id": { "type": "string", "description": "External identifier from source_system. If supplied, source_system is required.", "example": "BRK-000123", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Party-specific data (name, contact details, identifiers, etc.)", "example": { "first_name": "Takeshi", "last_name": "Yamamoto", "email": "t.yamamoto@example.jp", "phone": "+81312345678" } }, "created_by": { "type": "string", "description": "Identifier of the user or service creating this party", "example": "admin-user-001" }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required when status is merged; rejected for non-merged statuses.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "CreatePaymentRequest": { "type": "object", "required": [ "amount", "payment_method" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Payment amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the payment purpose", "example": "Ad-hoc premium payment \u2014 health gap cover" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the associated resource (premium, claim, etc.)", "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Type of the referenced resource", "example": "premium" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the party associated with this payment. Must be a valid party ID within the tenant.", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value metadata", "example": { "source": "broker-portal", "broker_id": "BRK-0042" } } }, "additionalProperties": false }, "CreatePolicyRequest": { "type": "object", "required": [ "product_id", "effective_date", "expiry_date", "parties" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "Identifier of the product to issue the policy under", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "effective_date": { "type": "string", "format": "date", "description": "Date from which the policy provides coverage", "example": "2026-04-01" }, "expiry_date": { "type": "string", "format": "date", "description": "Date on which the policy coverage ends", "example": "2027-03-31" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Policy-specific data", "example": { "sum_insured": 250000, "territory": "EU" } }, "parties": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyPartyRequest" }, "description": "Parties to assign to the policy (at least one required)" }, "created_by": { "type": "string", "description": "Identifier of the user or service creating this policy", "example": "agent-user-005" }, "binding_mode": { "type": "string", "enum": [ "individual", "group" ], "default": "individual", "description": "Policy binding mode. When omitted, defaults to \"individual\" for backward\ncompatibility. Set to \"group\" for master policy inception (group/employer/family).\n" }, "group_context": { "type": "object", "nullable": true, "description": "Required when binding_mode=group; must be absent for individual policies.\nDescribes the group contract metadata.\n", "properties": { "group_type": { "type": "string", "enum": [ "family", "employer" ], "description": "Type of group arrangement" }, "group_name": { "type": "string", "description": "Optional display name for the group" }, "external_group_ref": { "type": "string", "description": "Optional caller-supplied correlation key for the group" } }, "additionalProperties": false } }, "additionalProperties": false }, "CreateProductRequest": { "type": "object", "required": [ "product_code", "name", "type", "description", "currency", "covers", "terms", "attributes" ], "properties": { "product_code": { "type": "string", "description": "Human-readable product code (must be unique within the tenant)", "example": "MOTOR-TPL-2026" }, "name": { "type": "string", "description": "Display name of the product", "example": "Motor Third-Party Liability" }, "type": { "type": "string", "description": "Product classification", "example": "motor", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "description": { "type": "string", "description": "Detailed description of the product", "example": "Mandatory third-party liability cover for motor vehicles" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "GBP" }, "attributes": { "type": "object", "required": [ "base_premium" ], "properties": { "base_premium": { "type": "number", "description": "Required base premium amount in the smallest currency unit (e.g. cents). Must be positive. governed contract: no silent defaults.", "example": 15000, "x-axiom-money-classification": "json-number-money-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money", "x-axiom-money-risk": "json-number-can-lose-exactness" } }, "additionalProperties": true, "description": "Product configuration including required base_premium. governed contract: missing base_premium is an error, not a default.", "example": { "base_premium": 15000, "region": "EMEA", "regulatory_class": "compulsory" } }, "covers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AddCoverRequest" }, "description": "Required: at least one coverage section (governed contract: no silent defaults)" }, "terms": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ProductTermCreate" }, "description": "Required: at least one configurable term (governed contract: no silent defaults). Create-shaped: no server-minted term id (governed contract / governed contract)." } }, "additionalProperties": false }, "CreateQuoteRequest": { "type": "object", "required": [ "effective_date", "expiry_date" ], "description": "Exactly one of pricing_snapshot_id, products, or product_id must be provided.\npricing_snapshot_id and products are mutually exclusive (422 PRICING_INPUT_CONFLICT).\nIf none is provided, returns 422 PRICING_INPUT_REQUIRED.\n", "properties": { "pricing_snapshot_id": { "type": "string", "description": "Reference to a prior rate result snapshot (mutually exclusive with products)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "products": { "type": "array", "description": "Inline product + risk_profile pairs (mutually exclusive with pricing_snapshot_id)", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "risk_profile": { "type": "object", "additionalProperties": false } }, "additionalProperties": false } }, "product_id": { "type": "string", "description": "Legacy single-product shorthand (backward compatible)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date", "example": "2026-04-01" }, "expiry_date": { "type": "string", "format": "date", "example": "2027-04-01" }, "underwriting_data": { "type": "object", "additionalProperties": true, "example": { "age": 35, "vehicle_value": 25000 } }, "covers_selected": { "type": "array", "items": { "type": "string" }, "default": [] }, "comparison_ref": { "type": "string", "description": "Links comparison sets for quote comparison" }, "supersedes": { "type": "string", "description": "Quote ID this quote supersedes" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Party snapshot for bind-time matching" } }, "additionalProperties": false }, "CreateRecoveryRequest": { "type": "object", "required": [ "recovery_type", "amount", "currency", "received_at", "reason", "evidence_refs" ], "properties": { "recovery_type": { "type": "string", "enum": [ "subrogation", "salvage" ], "description": "Type of recovery. Closed enum. `subrogation`: claim-level recovery against a liable third party. `salvage`: item-level recovery from damaged goods.\n", "example": "subrogation" }, "claim_item_id": { "type": "string", "format": "typed-prefix-id", "description": "Required for `salvage`, forbidden for `subrogation`. References the specific claim item being salvaged.\n", "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "third_party_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required for `subrogation`, optional for `salvage`. References the liable third-party via party ID.\n", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f9", "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "Recovery amount as string-encoded exact decimal in the smallest currency unit (e.g. cents). String encoding under the contract contract; no float on financial paths (governed contract).\n", "example": "5000000", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "USD" }, "received_at": { "type": "string", "format": "date-time", "description": "When the recovery was received (RFC 3339)", "example": "2026-03-15T10:30:00Z" }, "reason": { "type": "string", "description": "Reason for the recovery", "example": "Third party liability established via settlement agreement" }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Non-empty array of evidence references supporting this recovery", "example": [ "ev-settlement-001", "ev-police-report-042" ] } }, "additionalProperties": false }, "CreateReversalResponse": { "type": "object", "required": [ "reversal_entry_id", "original_entry_id", "transaction_id", "content_hash", "created_at" ], "properties": { "reversal_entry_id": { "type": "string", "description": "Ledger entry ID for the reversal entry.", "example": "rev-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_entry_id": { "type": "string", "description": "Ledger entry ID that was reversed.", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "transaction_id": { "type": "string", "description": "Transaction identifier shared by the reversal posting.", "example": "txn-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content_hash": { "type": "string", "description": "Canonical content hash for the reversal entry.", "example": "2f1c0b6e2c8a..." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the reversal was created.", "example": "2026-04-01T09:10:00Z" } }, "additionalProperties": false }, "CreateRulesetRequest": { "type": "object", "required": [ "code", "name", "entity_type", "description" ], "properties": { "code": { "type": "string", "description": "Machine-readable ruleset code (must be unique within the tenant)", "example": "home-contents-ke-v1", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable ruleset name", "example": "Kenya Home Contents Insurance" }, "entity_type": { "type": "string", "enum": [ "claims", "underwriting", "pricing", "claims_assessment", "document_completeness", "discount" ], "description": "Runtime rule lane this ruleset governs", "example": "pricing" }, "description": { "type": "string", "description": "Detailed description of the ruleset purpose", "example": "Validation and pricing rules for home contents cover in Kenya" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional metadata (jurisdiction, product line, etc.)", "example": { "jurisdiction": "KE", "product_line": "home_contents" } }, "base_ruleset": { "type": "string", "nullable": true, "description": "Code of an existing ruleset to use as a template. The new ruleset\ninherits rules from the base, which can then be overridden or extended.\n", "example": "home-contents-generic-v1" } }, "additionalProperties": false }, "CreateSubprocessorRequest": { "type": "object", "description": "JSON:API envelope for subprocessor creation request", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "required": [ "name", "service_scope" ], "properties": { "name": { "type": "string", "description": "Legal name of the subprocessor", "example": "Azure US East" }, "service_scope": { "type": "string", "description": "Services provided by the subprocessor", "example": "Disaster recovery and backup storage" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "CreateVendorRequest": { "type": "object", "description": "JSON:API envelope for vendor creation request", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "required": [ "name", "purpose", "classification", "accessed_data_classes", "integrations" ], "properties": { "name": { "type": "string", "description": "Legal or trading name of the vendor", "example": "MediCheck Health Services" }, "purpose": { "type": "string", "description": "Business purpose for engaging this vendor", "example": "Medical underwriting and claims verification" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Vendor data-access classification (A-E)", "example": "C" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Data classification labels for data the vendor will access", "example": [ "health", "personal_identifiable" ] }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Initial vendor status (defaults to draft if omitted)", "example": "draft" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional link to an existing Party record", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/CreateIntegrationInput" }, "description": "Initial integrations to create with the vendor" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "CreatedEvidenceRecordResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence record identifier.", "example": "3ed19703-e2bf-5cc7-80f3-c89ec9ec24b2", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence" ], "description": "JSON:API resource type for evidence records." }, "attributes": { "type": "object", "required": [ "evidence_id", "content_hash", "canonicalization_version" ], "properties": { "evidence_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "content_hash": { "type": "string" }, "canonicalization_version": { "type": "string", "example": "jcs-rfc8785-v1" } }, "additionalProperties": false } }, "additionalProperties": false }, "DeclineQuoteRequest": { "type": "object", "required": [ "reason_code" ], "properties": { "reason_code": { "type": "string", "description": "Machine-readable reason for declining the quote" } }, "additionalProperties": false }, "EndorsementResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyEndorsement" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Error": { "type": "object", "required": [ "status", "title" ], "properties": { "status": { "type": "string", "description": "HTTP status code as a string", "example": "422", "x-axiom-coded-value-classification": "platform-http-status-code" }, "code": { "type": "string", "description": "Application-specific error code", "example": "VALIDATION_ERROR", "pattern": "^[A-Z][A-Z0-9_]*$" }, "title": { "type": "string", "description": "Short, human-readable summary of the error", "example": "Validation Error" }, "detail": { "type": "string", "description": "Human-readable explanation of the error", "example": "Field 'policy_number' is required" }, "help_url": { "type": "string", "format": "uri", "description": "Documentation URL for this error code", "example": "https://developers.afr-dev.axiom.express/api/reference/0.1.22/errors/VALIDATION_ERROR/" }, "source": { "$ref": "#/components/schemas/ErrorSource" }, "meta": { "type": "object", "additionalProperties": true, "description": "Additional error metadata" } }, "additionalProperties": false }, "ErrorMeta": { "type": "object", "properties": { "correlation_id": { "type": "string", "description": "Request correlation ID for support reference", "example": "req-abc-123-def-456", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the error occurred", "example": "2026-02-07T12:00:00Z" }, "request_id": { "type": "string", "description": "Unique request identifier", "example": "req-789-ghi", "x-axiom-identifier-classification": "request-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Error" }, "description": "Array of error objects" }, "meta": { "$ref": "#/components/schemas/ErrorMeta" } }, "additionalProperties": false }, "ErrorSource": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the field that caused the error", "example": "/data/attributes/policy_number" }, "parameter": { "type": "string", "description": "Query parameter that caused the error", "example": "filter[status]" }, "header": { "type": "string", "description": "Header that caused the error", "example": "X-Tenant-Context" } }, "additionalProperties": false }, "EvaluatePartyGroupRequest": { "type": "object", "required": [ "party_id" ], "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "as_of": { "type": "string", "format": "date-time", "description": "Defaults to now() server-side" } }, "additionalProperties": false }, "Event": { "type": "object", "description": "A real-world incident (the events half of the events/assertions paired\nprimitive, governed contract). Read-only projection over the event schema.\n", "required": [ "id", "event_type", "occurred_at", "reported_at", "status" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "Event identity (wire form)", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "event_type": { "type": "string", "description": "Type of incident: accident, illness, theft, damage, death, etc.", "example": "accident" }, "event_subtype": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the incident occurred" }, "reported_at": { "type": "string", "format": "date-time", "description": "When the incident was reported" }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "description": "Event lifecycle status (free-form domain string)", "example": "validated", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "severity": { "type": "string" }, "location": { "type": "string" }, "coordinates": { "type": "object", "additionalProperties": true }, "event_details": { "type": "object", "additionalProperties": true, "description": "Domain-specific incident detail payload" }, "primary_party_id": { "type": "string", "format": "uuid", "nullable": true, "x-axiom-identifier-shape": "uuid" }, "involved_parties": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "policy_id": { "type": "string", "description": "Reference to the policy the incident is reported against", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_object_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "validation_method": { "type": "string" }, "validation_reference": { "type": "string" }, "estimated_loss": { "type": "integer", "format": "int64", "description": "Estimated loss in exact integer minor units (governed contract \u2014 never float), paired with currency", "example": 5000000 }, "currency": { "type": "string", "description": "Lowercase ISO-4217 currency for estimated_loss (governed contract)", "example": "zar" }, "requires_notification": { "type": "boolean" }, "notification_sent": { "type": "string", "format": "date-time", "nullable": true }, "notification_reference": { "type": "string" }, "reported_by": { "type": "string" }, "source_system": { "type": "string" }, "external_reference": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "description": { "type": "string", "description": "Human-readable event description" }, "investigation_notes": { "type": "string" } }, "additionalProperties": false }, "EventListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "EventReportRequest": { "type": "object", "required": [ "event_data" ], "properties": { "event_data": { "type": "string", "description": "JSON object (as a string) describing the event. Supported fields mirror\nthe Event projection's tenant-reportable fields: event_id, event_type,\nevent_subtype, occurred_at, reported_at, policy_id, policy_object_id,\nprimary_party_id, event_details, metadata, description, and the other\noptional event facts exposed on the Event schema.\n" } }, "additionalProperties": { "type": "string", "format": "binary" } }, "EventReportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/eventReportDTO" } }, "required": [ "data" ], "additionalProperties": true } ] }, "EventResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Event" } }, "required": [ "data" ], "additionalProperties": true } ] }, "EvidencePackResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence pack identifier.", "example": "00548ee3-5ea2-5e09-8975-93b2e0fe033e", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence-pack" ], "description": "JSON:API resource type for evidence packs." }, "attributes": { "type": "object", "required": [ "surface_code", "generated_at", "pack_hash", "evidence_entries" ], "properties": { "surface_code": { "type": "string", "description": "Regulatory surface used to assemble the pack.", "example": "conduct_claims" }, "generated_at": { "type": "string", "format": "date-time", "description": "Time the evidence pack was generated." }, "inputs_fingerprint": { "type": "string", "description": "Deterministic fingerprint of the inputs used for assembly." }, "pack_hash": { "type": "string", "description": "Deterministic hash of the assembled evidence pack." }, "assembly_rules": { "type": "object", "additionalProperties": true, "description": "Compliance pack reference and rule metadata used for assembly." }, "evidence_entries": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Evidence entries included in the pack." } }, "additionalProperties": false } }, "additionalProperties": false }, "EvidenceRecord": { "type": "object", "required": [ "id", "record_type", "subject_type", "subject_id", "content", "content_hash", "created_at", "created_by" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique evidence record identifier", "example": "c0e531a6-9deb-53a8-873b-9736a707f52b", "x-axiom-identifier-shape": "uuid" }, "record_type": { "type": "string", "description": "Classification of the evidence record.\nCommon types: decision_trace, approval_record, compliance_check,\nrule_evaluation, state_transition, document_verification.\n", "example": "decision_trace" }, "subject_type": { "type": "string", "description": "Type of the entity this evidence pertains to\n(e.g. policy, claim, premium, party, ruleset).\n", "example": "claim" }, "subject_id": { "type": "string", "description": "Identifier of the entity this evidence pertains to", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content": { "type": "object", "additionalProperties": true, "description": "Structured evidence payload. Contents vary by record_type but must\nbe self-contained and reproducible (platform principle \u2014 explainability).\nIncludes inputs, outputs, rule versions, and intermediate results.\n", "example": { "decision": "claim_approved", "inputs": { "claim_amount": 12500, "policy_excess": 2500, "cover_limit": 500000 }, "rule_version": "motor-claims-v3.2.0", "evaluation_steps": [ { "rule": "cover_active_check", "result": true }, { "rule": "excess_applied", "result": true, "excess_amount": 2500 }, { "rule": "within_cover_limit", "result": true } ], "net_payout": 10000 } }, "content_hash": { "type": "string", "readOnly": true, "description": "SHA-256 hash of the content payload. Enables tamper detection\nand integrity verification without inspecting the full content.\n", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the evidence record was created", "example": "2026-03-08T14:22:15Z" }, "created_by": { "type": "string", "readOnly": true, "description": "Identifier of the user or service that created this record", "example": "claims-adjudication-service" } }, "additionalProperties": false }, "EvidenceRecordResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence record identifier.", "example": "3ed19703-e2bf-5cc7-80f3-c89ec9ec24b2", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence" ], "description": "JSON:API resource type for evidence records." }, "attributes": { "type": "object", "required": [ "content_hash", "canonicalization_version", "integrity_status", "actor_type", "actor_id", "actor_original_id", "evidence_type", "entity_id", "entity_type", "occurred_at", "created_at" ], "properties": { "content_hash": { "type": "string" }, "canonicalization_version": { "type": "string", "example": "jcs-rfc8785-v1" }, "integrity_status": { "type": "string" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_type": { "type": "string" }, "entity_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "entity_type": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false }, "EvidenceRecordResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidenceRecordResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "HierarchyTerm": { "type": "object", "required": [ "id", "code", "name", "type", "parent_type", "parent_id" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique term identifier", "example": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this term", "example": "MAX-CLAIM-LIMIT", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Maximum Claim Limit" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the term", "example": "Maximum amount claimable per event" }, "type": { "type": "string", "enum": [ "condition", "limit", "exclusion" ], "description": "The kind of term.\n- condition: A prerequisite that must be met for coverage to apply\n- limit: A numeric boundary on coverage (e.g. maximum payout)\n- exclusion: A circumstance under which coverage does not apply\n", "example": "limit" }, "parent_type": { "type": "string", "description": "The type of parent entity (e.g. cover, cover_item)", "example": "cover" }, "parent_id": { "type": "string", "format": "uuid", "description": "Identifier of the parent entity", "example": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "x-axiom-identifier-shape": "uuid" }, "expression": { "type": "string", "nullable": true, "description": "CEL expression for evaluating this term", "example": "claim.amount <= 250000.00" }, "boundary": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/HierarchyTermBoundary" } ], "additionalProperties": true }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "HierarchyTermBoundary": { "type": "object", "description": "Numeric boundaries for limit-type hierarchy terms", "properties": { "min": { "type": "integer", "format": "int64", "nullable": true, "description": "Minimum boundary value in the smallest currency unit (e.g. cents) when monetary, or in the declared unit otherwise. Exact integer representation.", "example": 0 }, "max": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum boundary value in the smallest currency unit (e.g. cents) when monetary, or in the declared unit otherwise. Exact integer representation.", "example": 50000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "nullable": true, "description": "ISO 4217 currency code (when boundary is monetary)", "example": "EUR" }, "unit": { "type": "string", "nullable": true, "description": "Unit of measurement (when boundary is non-monetary)", "example": "days" } }, "additionalProperties": false }, "InboxMessageReceipt": { "type": "object", "required": [ "inbox_message_id", "receipt_status", "deduplication_key" ], "properties": { "inbox_message_id": { "type": "string", "format": "uuid", "description": "Assigned message identifier.", "x-axiom-identifier-shape": "uuid" }, "receipt_status": { "type": "string", "enum": [ "accepted", "duplicate" ], "description": "- accepted: New message, queued for processing.\n- duplicate: Message with this key already exists.\n" }, "deduplication_key": { "type": "string", "description": "Echo of the client-provided deduplication key." } }, "additionalProperties": false }, "InboxMessageReceiptResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/InboxMessageReceipt" } }, "additionalProperties": true } ] }, "Integration": { "type": "object", "required": [ "integration_id", "vendor_id", "system_name", "data_categories", "data_direction", "transfer_method" ], "properties": { "integration_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique integration identifier", "example": "ef3dae92-18c3-52d8-bb19-359e317362d6", "x-axiom-identifier-shape": "uuid" }, "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Vendor this integration belongs to", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "system_name": { "type": "string", "description": "Name of the external system being integrated", "example": "CloudSure Policy API" }, "data_categories": { "type": "array", "items": { "type": "string" }, "description": "Categories of data exchanged through this integration.\nAligns with data classification policy.\n", "example": [ "policy_data", "policyholder_pii", "premium_amounts" ] }, "data_direction": { "type": "string", "enum": [ "ingress", "egress", "bidirectional" ], "description": "Direction of data flow relative to Axiom.\n- ingress: Data flows from vendor into Axiom\n- egress: Data flows from Axiom to vendor\n- bidirectional: Data flows in both directions\n", "example": "bidirectional" }, "transfer_method": { "type": "string", "description": "Technical method used for data transfer\n(e.g. rest_api, sftp, webhook, message_queue, batch_file).\n", "example": "rest_api" } }, "additionalProperties": false }, "IntegrityResult": { "type": "object", "required": [ "entry_id", "status", "failure_code", "computed_hash", "stored_hash", "chain_depth" ], "properties": { "entry_id": { "type": "string", "description": "Ledger entry checked.", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "status": { "type": "string", "enum": [ "PASS", "FAIL" ], "description": "Integrity status for this entry.", "example": "PASS" }, "failure_code": { "type": "string", "description": "Failure code when status is FAIL; empty when the check passes.", "example": "" }, "computed_hash": { "type": "string", "description": "Hash computed from the current canonical entry content.", "example": "2f1c0b6e2c8a..." }, "stored_hash": { "type": "string", "description": "Hash stored with the entry.", "example": "2f1c0b6e2c8a..." }, "chain_depth": { "type": "integer", "description": "Number of lineage links inspected.", "example": 0 } }, "additionalProperties": false }, "IntegrityVerificationResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Integrity verification identifier.", "example": "d030a083-6627-5d10-a1ec-de4b762f556b", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "integrity-verification" ] }, "attributes": { "type": "object", "required": [ "verification_id", "expected_hash", "actual_hash", "status", "verified_at" ], "properties": { "verification_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "expected_hash": { "type": "string" }, "actual_hash": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "tampered", "missing", "corrected" ] }, "verified_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false }, "IntegrityVerificationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IntegrityVerificationResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "InvestigationRecord": { "type": "object", "properties": { "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "claim_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "state": { "type": "string", "enum": [ "assigned", "investigating", "findings_submitted", "closed" ] }, "disposition": { "type": "string", "enum": [ "substantiated", "unsubstantiated", "settled" ], "nullable": true }, "trigger_source": { "type": "string", "enum": [ "rule_threshold", "human_referral" ] }, "assigned_party_id": { "type": "string", "x-axiom-identifier-classification": "party-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "assigned_role_type": { "type": "string" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "fraud_rule_refs": { "type": "array", "items": { "type": "string" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "InvestigationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvestigationRecord" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Invoice": { "type": "object", "description": "Invoice resource. Field-level shape remains runtime-governed until the invoice resource schema is promoted.", "additionalProperties": true }, "InvoiceListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "InvoiceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ItemAssessment": { "type": "object", "properties": { "item_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the claim item being assessed", "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Approved amount for this item." }, "notes": { "type": "string", "description": "Assessment notes specific to this item", "example": "Flooring replacement quote verified with two independent suppliers" } }, "additionalProperties": false }, "JurisdictionFinding": { "type": "object", "properties": { "jurisdiction_code": { "type": "string", "example": "ZA" }, "status": { "type": "string", "enum": [ "pass", "fail", "needs_review" ] }, "evidence_references": { "type": "array", "items": { "type": "string" } }, "missing_evidence": { "type": "array", "items": { "type": "string" }, "description": "JSON paths of missing evidence fields" } }, "additionalProperties": false }, "LedgerCorrectionsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LineageNode" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerEntry": { "type": "object", "required": [ "id", "account_code", "entry_type", "amount", "currency", "entry_date", "status", "posted_at", "posted_by", "reference_type", "reference_id" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique ledger entry identifier", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" }, "account_code": { "type": "string", "description": "Account code identifying the ledger account.\nFollows a hierarchical naming convention (e.g. premium receivable,\nclaims payable, commission expense).\n", "example": "PREM-RCV-001" }, "entry_type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Type of ledger entry. Every financial transaction records balanced\ndebit and credit entries.\n- debit: Increases asset/expense accounts, decreases liability/revenue accounts\n- credit: Increases liability/revenue accounts, decreases asset/expense accounts\n", "example": "credit" }, "amount": { "type": "integer", "format": "int64", "description": "Monetary amount for this entry in the smallest currency unit (e.g. cents). Always positive; direction is determined by entry_type. Exact integer representation.", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "USD" }, "entry_date": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the accounting date for this entry", "example": "2026-03-01T00:00:00Z" }, "status": { "type": "string", "enum": [ "pending", "posted", "reversed" ], "description": "Current status of the ledger entry.\n- pending: Entry created but not yet posted to the ledger\n- posted: Entry has been posted and affects account balances\n- reversed: Entry has been reversed by a correcting entry\n", "example": "posted" }, "posted_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the entry was posted", "example": "2026-03-01T08:15:30Z" }, "posted_by": { "type": "string", "readOnly": true, "description": "Identifier of the user or service that posted this entry", "example": "premium-collection-service" }, "reference_type": { "type": "string", "description": "Type of the source entity that originated this ledger entry\n(e.g. premium, claim, adjustment).\n", "example": "premium" }, "reference_id": { "type": "string", "format": "uuid", "description": "Identifier of the source entity that originated this entry", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "LedgerEntryListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerIntegrityResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VerifyIntegrityResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerReversalResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateReversalResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LineageNode": { "type": "object", "required": [ "entry_id", "original_entry_id", "reversal_entry_id", "actor_type", "actor_id", "actor_original_id", "reason_code", "content_hash", "business_event_time" ], "properties": { "entry_id": { "type": "string", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_entry_id": { "type": "string", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "reversal_entry_id": { "type": "string", "example": "rev-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "example": "human" }, "actor_id": { "type": "string", "example": "user-1", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "example": "user-1", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "reason_code": { "type": "string", "example": "correction" }, "content_hash": { "type": "string", "example": "2f1c0b6e2c8a..." }, "business_event_time": { "type": "string", "format": "date-time", "example": "2026-04-01T09:10:00Z" } }, "additionalProperties": false }, "Money": { "type": "object", "required": [ "amount_minor", "currency_code" ], "properties": { "amount_minor": { "type": "integer", "format": "int64", "description": "Monetary amount in exact integer minor units (e.g. cents for ZAR/USD/EUR). Never float. The minor-unit exponent derives from currency_code \u2014 never hardcoded.", "example": 123456 }, "currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code (e.g. \"zar\"). Must be non-empty; absent currency is a caller error.", "example": "zar" } }, "additionalProperties": false }, "OffsetPaginationMeta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items matching the query", "example": 87 }, "limit": { "type": "integer", "description": "Maximum items per page", "example": 20 }, "offset": { "type": "integer", "description": "Number of items skipped", "example": 40 } }, "additionalProperties": false }, "PackVersionRef": { "type": "object", "properties": { "pack_id": { "type": "string", "format": "uuid", "description": "Compliance pack UUID", "x-axiom-identifier-shape": "uuid" }, "pack_version": { "type": "string", "description": "Semantic version of the pack", "example": "1.0.0" }, "ruleset_id": { "type": "string", "description": "Optional ruleset identifier", "x-axiom-identifier-classification": "ruleset-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_version": { "type": "string", "description": "Optional ruleset version" } }, "additionalProperties": false }, "PaginationMeta": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Current cursor position (can be used for bookmarking)", "example": "eyJpZCI6MTAwfQ==" }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page (null if no more pages)", "example": "eyJpZCI6MTIwfQ==" }, "has_more": { "type": "boolean", "description": "Whether more pages exist after this one", "example": true }, "page_size": { "type": "integer", "description": "Number of items in this page", "example": 20 }, "total_count": { "type": "integer", "description": "Total number of items matching the query.\nMay be omitted for performance on large datasets.\nWhen omitted, use `has_more` to determine if more pages exist.\n", "example": 150 } }, "additionalProperties": false }, "Party": { "type": "object", "required": [ "id", "party_type", "status", "source_system", "attributes", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "description": "Unique party identifier", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "party_type": { "type": "string", "enum": [ "individual", "organization", "system" ], "description": "Identity classification of the party. Contextual participation such as\nbroker, provider, agent, adjuster, or assessor belongs to PartyRole.role_type,\nnot Party.party_type.\n- individual: A natural person (policyholder, claimant, beneficiary)\n- organization: A legal entity (corporate client, reinsurer)\n- system: A non-human system identity used for platform mechanics\n", "example": "individual" }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "description": "Surviving Party identifier when status is merged. Required for status=merged; absent for every other status.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "external_id": { "type": "string", "nullable": true, "description": "Tenant-scoped identifier from the declared source system. Treat as PII-like; do not log raw request bodies containing it.", "example": "BRK-000123", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Extensible key-value pairs for party-specific data (name, date of birth, tax ID, etc.)", "example": { "first_name": "Maria", "last_name": "Eriksson", "date_of_birth": "1985-03-14", "email": "maria.eriksson@example.com" } }, "roles": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PartyRole" }, "description": "Roles assigned to this party across policies and claims" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was created", "example": "2026-01-15T09:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was last updated", "example": "2026-02-20T14:45:00Z" } }, "additionalProperties": false }, "PartyAuditEventItem": { "type": "object", "required": [ "id", "table_name", "operation", "performed_at", "actor_type", "actor_id", "actor_original_id", "rule_versions", "summary" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "table_name": { "type": "string" }, "operation": { "type": "string" }, "old_values": { "type": "object", "additionalProperties": true }, "new_values": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "performed_at": { "type": "string", "format": "date-time" }, "correlation_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "enum": [ "human", "service", "agent" ] }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "outcome": { "type": "string" }, "decision_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "decision-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "operation_code": { "type": "string" }, "purpose": { "type": "string", "description": "Declared business or compliance purpose recorded with the audit event." }, "compliance_category": { "type": "string", "description": "Compliance classification attached to the audit event." }, "data_classification": { "type": "string", "description": "Data classification for the audited payload or access." }, "additional_context": { "type": "object", "additionalProperties": true, "description": "Additional tenant/runtime context captured for the audit event." }, "rule_versions": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" } }, "additionalProperties": false }, "PartyAuditListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyAuditEventItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "PartyBalanceExplanation": { "type": "object", "required": [ "inputs", "rule_version", "computation", "entry_ids" ], "properties": { "inputs": { "type": "object", "additionalProperties": { "type": "string" } }, "rule_version": { "type": "string" }, "computation": { "type": "string" }, "entry_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "PartyBalanceFilter": { "type": "object", "properties": { "product_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "cover_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "category": { "type": "string", "nullable": true, "x-axiom-coded-value-classification": "tenant-catalogue-category" }, "role": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PartyBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyBalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyBalanceResult": { "type": "object", "required": [ "party_id", "as_of", "currency", "amount", "entry_count" ], "properties": { "party_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "as_of": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "description": "Decimal amount rendered as a string to preserve exact wire fidelity.", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "entry_count": { "type": "integer", "minimum": 0 }, "filters": { "$ref": "#/components/schemas/PartyBalanceFilter" }, "explanation": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PartyBalanceExplanation" } ], "additionalProperties": true } }, "additionalProperties": false }, "PartyContactListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactInfo" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyContactResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactInfo" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyDistributionChainResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Distribution chain traversal result", "required": [ "participants" ], "properties": { "participants": { "type": "array", "items": { "type": "object", "required": [ "party_id", "depth", "path" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "depth": { "type": "integer" }, "relationship_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "relationship_type": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "selected_path_rank": { "type": "integer" } }, "additionalProperties": false } }, "explanation": { "type": "object", "nullable": true, "description": "Traversal reasoning under the governed contract.", "properties": { "as_of": { "type": "string", "format": "date-time" }, "start_party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "filters": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "types": { "type": "array", "items": { "type": "string" } }, "max_depth": { "type": "integer" } }, "additionalProperties": false }, "candidate_paths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "winning_path": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyExternalIDSourceSystem": { "type": "string", "enum": [ "unmapped", "kelevra_native", "broker_crm", "underwriter_pas" ], "description": "Authoritative alpha registry for Party external identifier provenance.\n`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.\n", "example": "broker_crm" }, "PartyGroup": { "type": "object", "required": [ "id", "group_type", "status", "id_namespace", "display_name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique party-group identifier", "example": "d9af24ca-ffcb-5bed-b8ef-ae867ef80388", "x-axiom-identifier-shape": "uuid" }, "group_type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "Membership resolution strategy.\n- static: members are managed manually via the /members endpoints\n- dynamic: members resolve via a CEL rule referenced by membership_rule;\n on-demand evaluation via POST /evaluate\n", "example": "static" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Lifecycle status. Soft delete flips to inactive \u2014 the group and its\nmemberships are preserved for audit (governed contract).\n", "example": "active" }, "id_namespace": { "type": "string", "description": "Namespace for external_id (DEFAULT tenant)", "example": "tenant" }, "external_id": { "type": "string", "nullable": true, "description": "Optional tenant-supplied identifier, unique per (tenant, id_namespace, group_type)", "example": "acme-employees", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "display_name": { "type": "string", "description": "Human-readable group name", "example": "ACME Employees" }, "description": { "type": "string", "nullable": true, "description": "Free-form purpose / semantics", "example": "All employees of ACME Corp as of the current payroll run" }, "membership_rule": { "type": "object", "nullable": true, "description": "CEL rule reference for dynamic groups. Shape is `{\"rule_id\": \"...\"}`\nreferencing a rule in the shared rules catalog. MUST be null when\ngroup_type = static; MUST be non-null when group_type = dynamic.\n", "additionalProperties": true, "example": { "rule_id": "rule-party-age-over-18" } }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-18T09:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-18T09:30:00Z" }, "created_by_actor_type": { "type": "string", "readOnly": true, "description": "Actor attribution under the governed contract", "example": "human" }, "created_by_actor_id": { "type": "string", "readOnly": true, "example": "user-marcus@acme.example", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupAuditEntry": { "type": "object", "required": [ "id", "table_name", "operation", "performed_at", "actor_type", "actor_id", "actor_original_id", "rule_versions", "summary" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "table_name": { "type": "string" }, "operation": { "type": "string" }, "old_values": { "type": "object", "additionalProperties": true }, "new_values": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "performed_at": { "type": "string", "format": "date-time" }, "correlation_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "enum": [ "human", "service", "agent" ] }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "outcome": { "type": "string" }, "decision_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "decision-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "operation_code": { "type": "string" }, "rule_versions": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" } }, "additionalProperties": false }, "PartyGroupAuditListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupAuditEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "PartyGroupDetail": { "type": "object", "required": [ "party_group", "members" ], "properties": { "party_group": { "$ref": "#/components/schemas/PartyGroup" }, "members": { "type": "array", "description": "Active memberships as of the query time (or ?as_of=)", "items": { "$ref": "#/components/schemas/PartyGroupMembership" } } }, "additionalProperties": false }, "PartyGroupDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupDetail" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupEvaluationResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupEvaluationResult": { "type": "object", "required": [ "group_id", "party_id", "is_member", "evaluated_at" ], "description": "Read-only dry-run result of evaluating a dynamic group's membership rule\nagainst a candidate party. Does NOT mutate state.\n", "properties": { "group_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "is_member": { "type": "boolean", "description": "Whether the rule accepts this party for this group" }, "rule_id": { "type": "string", "nullable": true, "description": "The rule that was evaluated", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_type": { "type": "string", "nullable": true, "example": "party_grouping" }, "evaluated_at": { "type": "string", "format": "date-time" }, "explanation_summary": { "type": "string", "description": "under the governed contract \u2014 concise trace of which clauses matched or failed", "example": "party_type == individual: matched; attributes.age >= 18: matched" } }, "additionalProperties": false }, "PartyGroupFlatMember": { "type": "object", "required": [ "party_id", "found_at_depth" ], "description": "One party reachable from a group via recursive membership expansion", "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "found_at_depth": { "type": "integer", "minimum": 1, "description": "BFS depth at which this party was first reached (1 = direct member)" }, "via_path": { "type": "array", "items": { "type": "string" }, "description": "Chain of group ids from the start group to this party" }, "membership_id": { "type": "string", "format": "uuid", "description": "The membership row that connected this party at the first depth found", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PartyGroupFlatMemberListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupFlatMember" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroup" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupMembership": { "type": "object", "required": [ "id", "group_id", "member_type", "member_id", "valid_from", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "x-axiom-identifier-shape": "uuid" }, "group_id": { "type": "string", "format": "uuid", "description": "FK to party_groups.id", "x-axiom-identifier-shape": "uuid" }, "member_type": { "type": "string", "enum": [ "party", "group" ], "description": "Polymorphic member kind. `party` means member_id references parties.id;\n`group` means member_id references party_groups.id (nested membership).\n", "example": "party" }, "member_id": { "type": "string", "format": "uuid", "description": "FK to parties.id OR party_groups.id per member_type", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time", "description": "Membership start (inclusive)", "example": "2026-04-18T09:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Membership end (exclusive); null = currently active" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by_actor_type": { "type": "string", "readOnly": true }, "created_by_actor_id": { "type": "string", "readOnly": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupMembershipResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupMembership" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupMembershipView": { "type": "object", "required": [ "group_id", "name", "grouping_rule_id", "effective_from", "via_policy_id" ], "properties": { "group_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "name": { "type": "string" }, "grouping_rule_id": { "type": "string", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "via_policy_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroup" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupRole": { "type": "object", "required": [ "id", "role_type", "context", "effective_from" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "x-axiom-identifier-shape": "uuid" }, "role_type": { "type": "string", "enum": [ "sponsor", "provider", "beneficiary", "accepted_provider_network" ], "description": "Role played by the group.\n- sponsor: Group sponsoring a scheme (e.g. employer on a group health policy)\n- provider: Group acting as a service provider\n- beneficiary: Group entitled to benefits\n- accepted_provider_network: Provider-network group accepted on a Product context. Requires composition_type=provider_network on the assignee group and\n entity_type=product on the role context.\n", "example": "sponsor" }, "context": { "type": "object", "required": [ "entity_type", "entity_id" ], "description": "Entity the role is held against (policy, claim, party, etc.)", "properties": { "entity_type": { "type": "string", "example": "policy" }, "entity_id": { "type": "string", "example": "policy-12345", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "effective_from": { "type": "string", "format": "date-time", "example": "2026-04-18T09:30:00Z" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revocation_reason": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PartyGroupRoleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupRole" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupRoleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupRole" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyIdentityItem": { "type": "object", "required": [ "id", "identity_type", "identity_value", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "pti_01J9ZXKP8WQRM2N4V6T5S3D7F5", "x-axiom-identifier-shape": "typed-prefix" }, "identity_type": { "type": "string", "description": "Type of identity document (e.g. passport, national_id, tax_number, company_registration)", "example": "passport" }, "identity_value": { "type": "string", "description": "The identity document number or value", "example": "AB1234567" }, "issuing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code of issuing authority", "example": "GB" }, "expiry_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiry date of the identity document", "example": "2032-06-15" }, "status": { "type": "string", "enum": [ "unverified", "verified", "expired", "revoked" ], "example": "unverified" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, "additionalProperties": false }, "PartyIdentityListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyIdentityItem" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyIdentityResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyIdentityItem" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyLifecycleStatus": { "type": "string", "enum": [ "active", "inactive", "suspended", "deceased", "merged", "opted_out" ], "description": "Current Party lifecycle status.\n- active: Party can participate in transactions.\n- inactive: Party is no longer active.\n- suspended: Party is temporarily suspended pending review.\n- deceased: Natural-person Party is terminally deceased.\n- merged: Duplicate Party has been merged into merged_into_party_id and rejects later Party-scoped mutations.\n- opted_out: Party has opted out of new contact capture; historical contact reads remain available.\n", "example": "active" }, "PartyListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Party" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyPaymentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyPolicyGroupListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupMembershipView" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRelationshipItem": { "type": "object", "description": "Relationship resource per parties.RelationshipResponse", "required": [ "id", "from_party_id", "to_party_id", "relationship_type", "effective_from", "created_by" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "ptr_01J9ZXKP8WQRM2N4V6T5S3D7F6", "x-axiom-identifier-shape": "typed-prefix" }, "from_party_id": { "type": "string", "format": "typed-prefix-id", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "to_party_id": { "type": "string", "format": "typed-prefix-id", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "relationship_type": { "type": "string", "description": "Tenant `catalogue.relationship_types` code." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "created_by": { "type": "string" } }, "additionalProperties": false }, "PartyRelationshipListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRelationshipItem" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRelationshipResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyRelationshipItem" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Party" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRole": { "type": "object", "required": [ "id", "role_type", "context", "status", "assigned_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "description": "Unique role assignment identifier", "example": "rol_01j9zxkp8wqrm2n4v6t5s3d7f3", "x-axiom-identifier-shape": "typed-prefix" }, "role_type": { "type": "string", "description": "Tenant `catalogue.role_types` code assigned to the party. Bootstrap\nseed codes include policyholder, insured, beneficiary, broker, sponsor,\nand accepted_provider_network, but tenants may govern additional role\ntypes through the catalogue.\n", "example": "policyholder" }, "context": { "$ref": "#/components/schemas/RoleContext" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this role assignment is currently active", "example": "active" }, "assigned_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the role was assigned", "example": "2026-01-15T09:30:00Z" } }, "additionalProperties": false }, "PartyRoleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRole" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyRole" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleRevocationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "string", "format": "typed-prefix-id", "description": "Revoked role assignment identifier.", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleTypeEntry": { "type": "object", "required": [ "code", "display_name", "universal", "assignable_context_types", "requires_attribution" ], "properties": { "code": { "type": "string", "description": "Wire-stable party role type code.", "example": "policyholder", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "display_name": { "type": "string", "description": "Human-readable role type label.", "example": "Policyholder" }, "universal": { "type": "boolean", "description": "True when the role type is universal across tenants.", "example": true }, "assignable_context_types": { "type": "array", "description": "Context types where this role type may be assigned.", "items": { "type": "string" }, "example": [ "policy", "policy_item" ] }, "requires_attribution": { "type": "boolean", "description": "True when the role assignment requires actor attribution.", "example": true }, "regulatory_category": { "type": "string", "description": "Regulatory designation when one applies.", "example": "FAIS representative" }, "sector_hint": { "type": "string", "description": "Sector context for non-universal role types.", "example": "health" } }, "additionalProperties": false }, "PayClaimRequest": { "type": "object", "required": [ "paid_amount", "payment_method", "processed_by" ], "properties": { "paid_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount to disburse (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "payment_method": { "type": "string", "description": "Payment disbursement method", "example": "bank_transfer" }, "payment_notes": { "type": "string", "nullable": true, "description": "Notes accompanying the payment", "example": "Final settlement \u2014 claim fully resolved" }, "processed_by": { "type": "string", "description": "Identifier of the user or system processing the payment", "example": "payments-officer-mk-003" }, "authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "governed contract authorisation row to cite and gate before payment.", "example": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "x-axiom-identifier-shape": "uuid" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata for the payment", "example": { "bank_reference": "JPMC-ACH-2026030801", "beneficiary_account": "****4521" } } }, "additionalProperties": false }, "PayClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimPayment" }, "ledger_entries": { "type": "array", "description": "Ledger entries created by the claim payment", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": true } ] }, "Payment": { "type": "object", "required": [ "id", "amount", "status", "payment_method", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payment identifier", "readOnly": true, "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Payment amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the payment purpose", "example": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the associated resource (premium, claim, etc.)", "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Type of the referenced resource (e.g. premium, claim, refund)", "example": "premium" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value metadata for integration and operational data", "example": { "bank_reference": "ABSA-EFT-20260401-0042", "batch_id": "BATCH-2026-04-01", "reconciliation_status": "matched" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment record was created", "readOnly": true, "example": "2026-04-01T06:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment record was last updated", "readOnly": true, "example": "2026-04-01T08:30:00Z" }, "processed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the payment was successfully processed (null if not yet processed)", "readOnly": true, "example": "2026-04-01T08:30:00Z" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the party (policyholder, beneficiary, etc.) associated with this payment. Nullable for backward compatibility with payments created before party linkage.", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "PaymentFrequency": { "type": "string", "enum": [ "monthly", "quarterly", "half_yearly", "annual" ], "description": "Payment schedule frequency:\n- `monthly` \u2014 Payment due every month\n- `quarterly` \u2014 Payment due every 3 months\n- `half_yearly` \u2014 Payment due every 6 months\n- `annual` \u2014 Payment due once per year\n", "example": "monthly" }, "PaymentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentMethod": { "type": "string", "enum": [ "bank_transfer", "credit_card", "debit_order", "cash", "cheque" ], "description": "Supported payment methods:\n- `bank_transfer` \u2014 Electronic funds transfer (EFT) or wire transfer\n- `credit_card` \u2014 Credit card payment via payment gateway\n- `debit_order` \u2014 Recurring debit order (direct debit) from bank account\n- `cash` \u2014 Cash payment (recorded manually, typically at branch)\n- `cheque` \u2014 Cheque payment (subject to clearing period)\n", "example": "debit_order" }, "PaymentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentSchedule": { "type": "object", "required": [ "id", "policy_id", "frequency", "amount", "status", "next_due_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payment schedule identifier", "readOnly": true, "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "pattern": "^pol_[0-9a-z]+$", "description": "Reference to the policy this schedule services, rendered in canonical typed-prefix form.", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-shape": "typed-prefix" }, "frequency": { "$ref": "#/components/schemas/PaymentFrequency" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Scheduled payment amount per period (exact integer minor units + lowercase ISO-4217 currency code)." }, "status": { "$ref": "#/components/schemas/PaymentScheduleStatus" }, "next_due_date": { "type": "string", "format": "date", "description": "Next scheduled payment date", "example": "2026-05-01" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was created", "readOnly": true, "example": "2026-01-15T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was last updated", "readOnly": true, "example": "2026-04-01T08:30:00Z" } }, "additionalProperties": false }, "PaymentScheduleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSchedule" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentScheduleStatus": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ], "description": "Payment schedule lifecycle status:\n- `active` \u2014 Schedule is running and will generate payments on due dates\n- `paused` \u2014 Schedule is temporarily suspended (e.g. payment holiday, dispute)\n- `completed` \u2014 Schedule has run its full term (policy expired or fully paid)\n- `cancelled` \u2014 Schedule has been permanently cancelled\n", "example": "active" }, "PaymentStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ], "description": "Payment lifecycle status:\n- `pending` \u2014 Payment has been created but not yet submitted for processing\n- `processing` \u2014 Payment has been submitted and is being processed by the payment provider\n- `completed` \u2014 Payment has been successfully processed and confirmed\n- `failed` \u2014 Payment processing failed (insufficient funds, declined, technical error)\n- `cancelled` \u2014 Payment was cancelled before processing completed\n", "example": "pending" }, "Policy": { "type": "object", "required": [ "id", "policy_number", "product_id", "status", "effective_date", "expiry_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique policy identifier", "example": "204a5555-2273-5dfd-8bcc-09717add6538", "x-axiom-identifier-shape": "uuid" }, "policy_number": { "type": "string", "readOnly": true, "description": "Human-readable policy number assigned by the system", "example": "POL-2026-000142" }, "product_id": { "type": "string", "format": "uuid", "description": "Identifier of the product this policy is issued under", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "status": { "type": "string", "enum": [ "draft", "issued", "active", "terminated" ], "description": "Current status of the policy. The policy lifecycle follows this state machine:\n\n```\ndraft -> issued -> active -> terminated\n```\n\nTransitions:\n- `draft` -> `issued`: Policy has been reviewed and formally issued\n- `issued` -> `active`: Policy has reached its effective date and is providing coverage\n- `active` -> `terminated`: Policy coverage has ended\n\nThe `terminated` state carries a termination type that records the business\nreason for exit. Valid termination types include:\n- `cancelled` \u2014 terminated before natural expiry (voluntary or involuntary)\n- `expired` \u2014 reached its expiry date and coverage ended naturally\n- `lapsed` \u2014 terminated due to non-payment of premiums\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nPer-value descriptions:\n- `draft`: Policy is being prepared; not yet formally issued or providing coverage\n- `issued`: Policy has been formally issued but has not yet reached its effective date\n- `active`: Policy is in force and providing coverage to the insured parties\n- `terminated`: Policy coverage has ended; see termination record for reason (cancelled, expired, or lapsed)\n", "example": "active" }, "effective_date": { "type": "string", "format": "date", "description": "Date from which the policy provides coverage (inclusive)", "example": "2026-03-01" }, "expiry_date": { "type": "string", "format": "date", "description": "Date on which the policy coverage ends (inclusive)", "example": "2027-02-28" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value pairs for policy-specific data", "example": { "sum_insured": 250000, "territory": "EU", "renewal_count": 0 } }, "parties": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PolicyPartyRole" }, "description": "Parties and their roles on this policy" }, "premiums": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PolicyPremiumScheduleItem" }, "description": "Premium schedule for this policy" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the policy was created", "example": "2026-02-28T11:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the policy was last updated", "example": "2026-03-01T09:15:00Z" } }, "additionalProperties": false }, "PolicyBindRequest": { "type": "object", "required": [ "parties", "payment_method", "bound_by" ], "description": "Two bind modes: (1) quote-backed \u2014 provide quote_id; or (2) inline \u2014 provide product_id, effective_date, and expiry_date. parties, payment_method, and bound_by are always required.", "properties": { "quote_id": { "type": "string", "description": "Quote identifier for quote-backed bind. Mutually exclusive with inline fields (product_id, effective_date, expiry_date).", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "description": "Product identifier for inline bind. Required when quote_id is not provided.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp for policy activation. Required for inline bind (when quote_id is not provided)." }, "expiry_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp for policy expiry. Required for inline bind (when quote_id is not provided)." }, "underwriting_data": { "type": "object", "additionalProperties": true }, "parties": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ] } }, "additionalProperties": false } }, "payment_method": { "type": "string" }, "bound_by": { "type": "string" }, "binding_mode": { "type": "string", "enum": [ "individual", "group" ], "default": "individual", "description": "Policy binding mode. Defaults to \"individual\" for backward compatibility. Set to \"group\" for master policy inception." }, "group_context": { "type": "object", "nullable": true, "description": "Required when binding_mode=group; must be absent for individual.", "properties": { "group_type": { "type": "string", "enum": [ "family", "employer" ] }, "group_name": { "type": "string" }, "external_group_ref": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "PolicyBindResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyBindResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyBindResult": { "type": "object", "description": "The bound-policy payload returned in the SuccessEnvelope data field.", "required": [ "policy_id", "policy_number", "status", "premium_breakdown", "bound_at", "premium_id" ], "properties": { "policy_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_number": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "premium_breakdown": { "type": "object", "additionalProperties": true }, "bound_at": { "type": "string", "format": "date-time" }, "premium_id": { "type": "string", "description": "ID of the premium record created during bind (governed contract). Always present on success.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "explanation_tree_id": { "type": "string", "description": "ID of the bind explanation tree (governed contract), when produced.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" }, "description": "Ledger entry IDs produced during bind, when applicable." } }, "additionalProperties": false }, "PolicyEndorsement": { "type": "object", "required": [ "id", "policy_id", "endorsement_number", "type", "description", "effective_date", "status", "endorsed_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique endorsement identifier", "example": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the policy being endorsed", "example": "204a5555-2273-5dfd-8bcc-09717add6538", "x-axiom-identifier-shape": "uuid" }, "endorsement_number": { "type": "string", "readOnly": true, "description": "Sequential endorsement number within the policy", "example": "END-001" }, "type": { "type": "string", "description": "Classification of the endorsement (e.g. amendment, addition, deletion, correction)", "example": "amendment", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "description": { "type": "string", "description": "Human-readable description of what this endorsement changes", "example": "Update insured address and increase sum insured from 250,000 to 300,000" }, "effective_date": { "type": "string", "format": "date", "description": "Date from which the endorsement takes effect", "example": "2026-06-01" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ], "description": "Processing status of the endorsement.\n- pending: Endorsement has been submitted but not yet applied\n- applied: Endorsement has been applied to the policy\n- rejected: Endorsement was rejected (e.g. failed validation)\n", "example": "applied" }, "changes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Structured representation of the changes made by this endorsement", "example": { "sum_insured": { "from": 250000, "to": 300000 }, "address": { "from": "10 Downing Street, London", "to": "221B Baker Street, London" } } }, "endorsed_by": { "type": "string", "description": "Identifier of the user or process that created this endorsement", "example": "underwriter-user-003" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the endorsement was created", "example": "2026-05-28T14:00:00Z" } }, "additionalProperties": false }, "PolicyListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyPartyRequest": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "format": "uuid", "description": "Identifier of an existing party to assign to the policy", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "role": { "type": "string", "description": "Role to assign the party on this policy (e.g. policyholder, dependent, insured, beneficiary)", "example": "policyholder" } }, "additionalProperties": false }, "PolicyPartyRole": { "type": "object", "required": [ "party_id", "party_type", "role", "status", "assigned_at" ], "properties": { "party_id": { "type": "string", "format": "uuid", "description": "Identifier of the party", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "party_type": { "type": "string", "description": "Classification of the party (e.g. individual, organization)", "example": "individual" }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ], "description": "Role of the party on this policy", "example": "policyholder" }, "status": { "type": "string", "enum": [ "active", "inactive", "revoked" ], "description": "Whether this party-role assignment is currently active or has been revoked", "example": "active" }, "assigned_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was assigned to this policy", "example": "2026-02-28T11:00:00Z" } }, "additionalProperties": false }, "PolicyPremiumScheduleItem": { "type": "object", "required": [ "id", "amount", "due_date", "status", "payment_method" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique premium instalment identifier", "example": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "x-axiom-identifier-shape": "uuid" }, "amount": { "type": "integer", "format": "int64", "description": "Premium amount due for this instalment in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 11500, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "due_date": { "type": "string", "format": "date", "description": "Date by which the premium payment is due", "example": "2026-04-01" }, "status": { "type": "string", "enum": [ "pending", "paid", "overdue", "waived" ], "description": "Payment status of this premium instalment.\n- pending: Payment has not yet been received and is not overdue\n- paid: Payment has been received and reconciled\n- overdue: Payment was not received by the due date\n- waived: Payment has been waived (e.g. goodwill, correction)\n", "example": "pending" }, "payment_method": { "type": "string", "description": "Method of payment (e.g. debit_order, card, bank_transfer, cash)", "example": "debit_order" } }, "additionalProperties": false }, "PolicyResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyVersion": { "type": "object", "required": [ "id", "policy_id", "version_number", "version_type", "effective_from", "created_at" ], "properties": { "id": { "type": "string", "description": "Typed-prefix policy-version identifier (pov_\u2026)", "readOnly": true, "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "description": "Typed-prefix parent policy identifier (pol_\u2026)", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "version_number": { "type": "integer", "description": "Sequential version number within the policy", "example": 2 }, "version_type": { "type": "string", "enum": [ "issuance", "endorsement", "renewal", "cancellation" ], "description": "Why this version was created" }, "effective_from": { "type": "string", "format": "date-time", "description": "When this version becomes effective (inclusive)" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "When this version ceases to be effective (null = current version)" }, "change_reason": { "type": "string", "description": "Human-readable reason for creating this version" }, "created_by": { "type": "string", "description": "Actor ID who created this version (governed contract)" }, "previous_version": { "type": "string", "description": "ID of the predecessor version (empty for first version)" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the version was created" } }, "additionalProperties": false }, "PolicyVersionListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyVersion" } }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyVersionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyVersion" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Premium": { "type": "object", "required": [ "id", "policy_id", "premium_type", "status", "currency", "base_premium", "total_discount", "total_surcharge", "tax_amount", "net_premium", "final_premium", "installment_count", "installment_amount_minor", "payment_frequency", "effective_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique premium identifier", "readOnly": true, "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "description": "Reference to the policy this premium belongs to, in the canonical\ntyped-prefix form (`pol_\u2026`, governed contract). Not a bare UUID.\n", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "party_id": { "type": "string", "description": "Optional reference to the party who owes this premium (the debtor /\npolicyholder), in the canonical typed-prefix form (`pty_\u2026`, governed contract).\nOmitted when unset (absent \u2260 unknown, governed contract).\n", "example": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "premium_type": { "type": "string", "description": "Classifier on the single aggregate premium (NOT a row-multiplier) \u2014 e.g.\n`initial`, `renewal`, `endorsement`, `adjustment` (governed contract). Variation\nis recorded as append-only ledger entries, never a second Premium row.\n", "example": "initial" }, "status": { "$ref": "#/components/schemas/PremiumStatus" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code (e.g. \"zar\", governed contract). Interprets every\n`*_minor` money field on this object; the minor-unit exponent is derived\nfrom this code, never hardcoded.\n", "example": "zar" }, "base_premium": { "type": "integer", "format": "int64", "description": "Base premium before discounts/surcharges/tax, in exact int64 minor units (governed contract, never float).", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "total_discount": { "type": "integer", "format": "int64", "description": "Total discount applied, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "total_surcharge": { "type": "integer", "format": "int64", "description": "Total surcharge applied, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "tax_amount": { "type": "integer", "format": "int64", "description": "Tax component, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "net_premium": { "type": "integer", "format": "int64", "description": "Canonical net premium (base \u2212 discount + surcharge + tax), in exact int64\nminor units (governed contract, never float). This is the canonical net field \u2014 render\nthis as the money headline, never base_premium.\n", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "final_premium": { "type": "integer", "format": "int64", "description": "Deprecated alias for net_premium \u2014 same value. Read net_premium\ninstead. Retained for back-compat with the PremiumCalculation shape.\n", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "installment_count": { "type": "integer", "description": "Number of instalments the premium is split into (1 = single payment).", "example": 1 }, "installment_amount_minor": { "type": "integer", "format": "int64", "description": "Per-instalment amount, in exact int64 minor units (governed contract, never float).", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "payment_frequency": { "type": "string", "description": "Payment cadence for the premium (e.g. `annual`, `monthly`, `quarterly`).", "example": "annual" }, "effective_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp from which the premium obligation is effective.", "example": "2026-03-01T00:00:00Z" }, "expiry_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp at which the premium obligation expires. Omitted when unset.", "example": "2027-03-01T00:00:00Z" }, "due_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp on which the premium is due. Omitted when unset.", "example": "2026-04-01T00:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the premium record was created", "readOnly": true, "example": "2026-03-01T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the premium record was last updated", "readOnly": true, "example": "2026-03-15T10:30:00Z" } }, "additionalProperties": false }, "PremiumListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Premium" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PremiumResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Premium" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PremiumStatus": { "type": "string", "enum": [ "draft", "pending", "active", "expired", "cancelled" ], "description": "Aggregate-premium record lifecycle status (contract rule \u2014 the record lifecycle, not the\ncollection lifecycle):\n- `draft` \u2014 Premium obligation recorded but not yet activated (e.g. a\n manually-entered / imported inflow obligation; never an authoritative\n owed figure, contract rule).\n- `pending` \u2014 Premium is awaiting activation.\n- `active` \u2014 Premium obligation is in force.\n- `expired` \u2014 Premium obligation has lapsed at end of its effective window.\n- `cancelled` \u2014 Premium obligation has been cancelled (e.g. policy\n cancellation mid-term).\n\nNote: `paid` / `overdue` are payment/collection state and live on the\ninstalment (PolicyPremiumScheduleItem.status / /v1/payment-schedules), NOT on\nthe aggregate premium \u2014 relocated, not retired (contract rule, governed contract).\n", "example": "draft" }, "PricingRule": { "type": "object", "required": [ "id", "name", "rule_type", "base_rate", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique pricing rule identifier", "example": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Display name of the pricing rule", "example": "Age Rating Factor" }, "rule_type": { "type": "string", "enum": [ "age_factor", "risk_factor", "coverage_factor" ], "description": "Classification of the pricing rule.\n- age_factor: Adjusts premium based on insured's age\n- risk_factor: Adjusts premium based on risk assessment\n- coverage_factor: Adjusts premium based on selected coverage options\n", "example": "age_factor" }, "base_rate": { "type": "number", "format": "double", "description": "Base rate or multiplier for this pricing rule", "example": 1.25 }, "expression": { "type": "string", "nullable": true, "description": "CEL expression for dynamic rate calculation", "example": "age >= 50 ? 1.5 : 1.0" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for rule configuration", "example": { "age_bands": [ { "min_age": 18, "max_age": 35, "factor": 1 }, { "min_age": 36, "max_age": 50, "factor": 1.25 } ] } }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this pricing rule is currently applied", "example": "active" } }, "additionalProperties": false }, "Product": { "type": "object", "required": [ "id", "product_code", "name", "type", "status", "description", "currency", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique product identifier", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "product_code": { "type": "string", "description": "Human-readable product code used for catalogue reference", "example": "HEALTH-COMP-2026" }, "name": { "type": "string", "description": "Display name of the product", "example": "Comprehensive Health Cover" }, "type": { "type": "string", "description": "Product classification (e.g. life, health, property, motor, liability)", "example": "health", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "status": { "type": "string", "enum": [ "draft", "active" ], "description": "Product lifecycle status.\n- draft: Product is being configured and is not yet available for policy issuance\n- active: Product is published and available for policy issuance\n", "example": "draft" }, "description": { "type": "string", "description": "Detailed description of the product and its coverage", "example": "Comprehensive health insurance covering inpatient, outpatient, and dental care" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code for premiums and limits", "example": "EUR" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value pairs for product-specific configuration", "example": { "underwriting_class": "standard", "renewable": true } }, "covers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Cover" }, "description": "Coverage sections included in this product" }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ProductTerm" }, "description": "Configurable terms and parameters for the product" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\") explaining\nthe product for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "pricing_rules": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PricingRule" }, "description": "Rules governing premium calculation" }, "commissions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Commission" }, "description": "Commission structures for intermediary roles" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the product was created", "example": "2026-01-10T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the product was last updated", "example": "2026-02-01T16:30:00Z" } }, "additionalProperties": false }, "ProductListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductRulesetBinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique binding identifier", "x-axiom-identifier-shape": "uuid" }, "product_id": { "type": "string", "description": "Typed product identifier", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_id": { "type": "string", "format": "uuid", "description": "Identifier of the bound ruleset", "x-axiom-identifier-shape": "uuid" }, "ruleset_type": { "type": "string", "description": "Pipeline stage this binding satisfies" }, "ruleset_version": { "type": "integer", "description": "Version number of the bound ruleset" }, "effective_from": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when this binding becomes active" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when this binding was superseded (null if still active)" }, "created_by": { "type": "string", "description": "Actor ID that created the binding" } }, "additionalProperties": false }, "ProductRulesetBindingListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRulesetBinding" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductTerm": { "type": "object", "required": [ "id", "code", "name", "data_type", "required" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique term identifier", "example": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this configurable term", "example": "POLICY-TERM-MONTHS", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Policy Term" }, "description": { "type": "string", "nullable": true, "description": "Explanation of this term and how it affects the product", "example": "Duration of the policy in months" }, "data_type": { "type": "string", "description": "Data type for this term's value (e.g. string, integer, number, boolean, date)", "example": "integer" }, "required": { "type": "boolean", "description": "Whether this term must be provided when issuing a policy", "example": true }, "default_value": { "type": "string", "nullable": true, "description": "Default value when not explicitly provided", "example": "12" }, "validations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ValidationRule" }, "description": "Validation rules applied to this term's value" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "ProductTermCreate": { "type": "object", "required": [ "code", "name", "data_type", "required" ], "properties": { "code": { "type": "string", "description": "Short code for this configurable term", "example": "POLICY-TERM-MONTHS", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Policy Term" }, "description": { "type": "string", "nullable": true, "description": "Explanation of this term and how it affects the product", "example": "Duration of the policy in months" }, "data_type": { "type": "string", "description": "Data type for this term's value (e.g. string, integer, number, boolean, date)", "example": "integer" }, "required": { "type": "boolean", "description": "Whether this term must be provided when issuing a policy", "example": true }, "default_value": { "type": "string", "nullable": true, "description": "Default value when not explicitly provided", "example": "12" }, "validations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ValidationRule" }, "description": "Validation rules applied to this term's value" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "ProrationAdjustmentComponent": { "type": "object", "description": "Typed effect emitted by a proration decision.", "required": [ "component_type", "consumer", "affected" ], "additionalProperties": false, "properties": { "component_type": { "type": "string", "enum": [ "money", "premium_earning", "cover_limit", "waiting_period", "cover_period", "savings_fund", "backpay_debt", "entitlement_restoration", "reinsurance", "refusal" ] }, "consumer": { "type": "string", "enum": [ "ledger", "entitlement_balance", "temporal_gate", "fund_balance", "earning_balance", "reinsurance_balance", "explanation_only" ] }, "affected": { "type": "object", "additionalProperties": true, "description": "References to the affected primitive instances." }, "amount_minor": { "type": "integer", "format": "int64", "description": "Exact integer minor units for money components." }, "currency": { "type": "string", "description": "Lowercase ISO-4217 currency when amount_minor is present." }, "ratio_bps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Exact basis-point ratio when the component represents a proportion." }, "effective_start": { "type": "string", "format": "date-time" }, "effective_end": { "type": "string", "format": "date-time" }, "reason_code": { "type": "string", "description": "Tenant-owned reason code or fail-closed code." }, "metadata": { "type": "object", "additionalProperties": true } } }, "ProrationAdjustmentDecision": { "type": "object", "description": "Event-effective proration decision resource.", "required": [ "id", "event_id", "status", "event_type", "proration_intent", "components", "ledger_entry_ids", "explanation_tree_id", "evidence_entry_id", "ruleset" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Proration decision UUID.", "example": "f5430790-ad21-526a-945d-f06736f06e55", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "event_id": { "type": "string", "description": "Triggering event identity in wire form.", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "status": { "type": "string", "enum": [ "posted", "evaluated", "refused" ] }, "event_type": { "type": "string", "description": "Event type resolved from the existing triggering event row." }, "proration_intent": { "type": "string", "description": "Tenant ruleset key used for evaluation." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ProrationAdjustmentComponent" } }, "ledger_entry_ids": { "type": "array", "description": "Ledger entry ids created by financial components; empty for zero-money/refused decisions.", "items": { "type": "string" } }, "explanation_tree_id": { "type": "string", "description": "Durable explanation tree identity in wire form.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "evidence_entry_id": { "type": "integer", "format": "int64", "description": "governed contract evidence journal entry id for the persisted decision." }, "ruleset": { "type": "object", "additionalProperties": false, "required": [ "ruleset_type", "ruleset_id", "ruleset_version", "resolved_at" ], "properties": { "ruleset_type": { "type": "string", "example": "proration_adjustments" }, "ruleset_id": { "type": "string", "x-axiom-identifier-classification": "ruleset-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_version": { "type": "string" }, "resolved_at": { "type": "string", "format": "date-time" } } }, "correction_of_decision_id": { "type": "string", "nullable": true, "description": "Original decision id when this decision corrects a prior one.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } }, "ProrationAdjustmentRequest": { "type": "object", "description": "Request to apply a tenant-owned event-effective proration decision. Tenant,\nactor, event type, event effective time, active policy version,\npolicy-product binding, affected party-role authority, affected\npolicy-object authority, product-cover/term authority, ruleset\nbinding/version, ledger categories, and balance-consumer authority are\nderived or validated by the server and must not be supplied as overrides by\nthe caller. Policy and product identities are governed references used for\nserver-side validation and binding resolution; caller-supplied\npolicy-version or product-version overrides are rejected.\n", "required": [ "policy_id", "product_id", "proration_intent", "affected", "effective_times" ], "additionalProperties": false, "properties": { "policy_id": { "type": "string", "description": "Policy identity in wire form.", "example": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "premium_id": { "type": "string", "description": "Optional premium identity in wire form when the decision affects a known premium.", "example": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "product_id": { "type": "string", "description": "Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.", "example": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "proration_intent": { "type": "string", "description": "Tenant ruleset key that declares what adjustment intent to evaluate.", "example": "mid_year_join" }, "reason": { "type": "string", "description": "Operator-supplied reason for the adjustment request.", "maxLength": 1024 }, "correction_of_decision_id": { "type": "string", "format": "uuid", "description": "Existing proration decision UUID corrected by this decision.", "x-axiom-identifier-shape": "uuid" }, "affected": { "type": "object", "additionalProperties": false, "required": [ "party_role_id" ], "properties": { "party_role_id": { "type": "string", "description": "Affected party-in-role identity in wire form.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "cover_id": { "type": "string", "description": "Affected cover identity or tenant cover code, if cover-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_term_id": { "type": "string", "description": "Affected cover-level term identity or tenant term code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_item_id": { "type": "string", "description": "Affected cover-item identity or tenant cover-item code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_item_term_id": { "type": "string", "description": "Affected cover-item term identity or tenant term code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_object_id": { "type": "string", "description": "Affected insured object identity in pob_ wire form, if object-specific.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "treaty_id": { "type": "string", "description": "Reserved for future governed treaty authority; current runtime rejects reinsurance proration until that authority substrate exists.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } }, "effective_times": { "type": "object", "additionalProperties": false, "required": [ "premium_period_start", "premium_period_end" ], "properties": { "premium_period_start": { "type": "string", "format": "date-time", "description": "Start of the premium period to evaluate." }, "premium_period_end": { "type": "string", "format": "date-time", "description": "End of the premium period to evaluate." }, "cover_start": { "type": "string", "format": "date-time", "description": "Start of the cover-effective interval when different from premium period." }, "cover_end": { "type": "string", "format": "date-time", "description": "End of the cover-effective interval when different from premium period." }, "entitlement_start": { "type": "string", "format": "date-time", "description": "Start of the entitlement interval when applicable." }, "entitlement_end": { "type": "string", "format": "date-time", "description": "End of the entitlement interval when applicable." } } }, "inputs": { "type": "object", "description": "Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.", "additionalProperties": true } } }, "ProrationAdjustmentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationAdjustmentDecision" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationBalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResult": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount", "item_count" ], "properties": { "currency": { "type": "string", "description": "Lowercase ISO-4217 currency for money balances." }, "amount": { "type": "string", "description": "Decimal string amount produced by the governed contract balance engine.", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "item_count": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "explanation": { "type": "object", "additionalProperties": true } } }, "QueryEvidenceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "Quote": { "type": "object", "required": [ "quote_id", "product_id", "effective_date", "expiry_date", "underwriting_data", "covers_selected", "pricing_snapshot", "created_at", "valid_until", "actor_type", "actor_id", "actor_original_id" ], "properties": { "quote_id": { "type": "string", "example": "qte-a1b2c3d4", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date-time" }, "expiry_date": { "type": "string", "format": "date-time" }, "underwriting_data": { "type": "object", "additionalProperties": true }, "covers_selected": { "type": "array", "items": { "type": "string" } }, "pricing_snapshot": { "type": "object", "description": "Full premium calculation result snapshot (JSONB)", "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "actor_type": { "type": "string", "description": "Actor type that created the quote (governed contract)", "example": "human" }, "actor_id": { "type": "string", "description": "Actor identifier that created the quote (governed contract)", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "description": "Original actor identifier before delegation (governed contract)", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "comparison_ref": { "type": "string", "description": "Links comparison sets for quote comparison" }, "supersedes_quote_id": { "type": "string", "description": "Quote ID this quote supersedes", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Party snapshot for bind-time matching" } }, "additionalProperties": false }, "QuoteListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "QuoteParty": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string" } }, "additionalProperties": false }, "QuoteResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecordClaimAuthorisationRequest": { "type": "object", "required": [ "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id" ], "properties": { "logical_authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Logical thread id for grant/amend/revoke chains. Generated when omitted.", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string", "description": "Sector-neutral transition verb.", "example": "authorisation-granted" }, "authorisation_kind": { "type": "string", "description": "Tenant-keyed authorisation kind.", "example": "pre-auth" }, "authorising_actor": { "type": "string", "format": "uuid", "description": "Party-in-role actor that granted the authorisation." }, "authorised_scope": { "type": "object", "additionalProperties": true, "description": "Typed grant envelope such as procedures, codes, or engagement scope." }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "description": "Exact integer minor units for the authorised budget ceiling.", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "nullable": true, "description": "Lowercase ISO-4217 currency code. Present iff budget_minor is present." }, "governing_version_kind": { "type": "string", "nullable": true, "description": "Governing-version discriminator such as catalogue, rule, cover, or engagement-terms." }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Immutable row-id revision of the governing version current at the decision date.", "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true, "description": "Tenant-keyed compliance kind such as accreditation or sanctions-screening." }, "compliance_outcome": { "type": "string", "nullable": true, "enum": [ "clear", "hit", "pending", "unset", "override" ], "description": "Compliance outcome consulted by the payment gate when payment cites this authorisation." }, "compliance_list_version": { "type": "string", "nullable": true, "description": "Tenant-supplied as-was list or standard version." }, "compliance_list_authority": { "type": "string", "nullable": true, "description": "Tenant-keyed list authority such as cms, ofac, ofsi, or eu." }, "decision_date": { "type": "string", "format": "date-time", "description": "Moment the authorisation decision was made." }, "explanation_node_id": { "type": "string", "format": "uuid", "description": "Explanation-node reference for the authorisation decision.", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true, "description": "Required by the persistence rule on revoke or withdrawal transitions." } }, "additionalProperties": false }, "RecordClaimAuthorisationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthorisationTransition" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecoveryEnvelopeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecoveryResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecoveryRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique recovery identifier", "readOnly": true, "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "claim_item_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "recovery_type": { "type": "string", "enum": [ "subrogation", "salvage" ] }, "third_party_party_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "type": "string", "description": "String-encoded exact decimal in smallest currency unit (governed contract)", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "RecoveryResponse": { "type": "object", "properties": { "recovery": { "$ref": "#/components/schemas/RecoveryRecord" }, "ledger_batch_ref": { "type": "string", "description": "Reference to the balanced ledger batch (transaction ID)", "example": "txn-a1b2c3d4" }, "explanation_root_id": { "type": "string", "description": "Root ID of the explanation tree (governed contract)", "example": "expl-e5f6a7b8", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_entry_id": { "type": "string", "description": "Evidence entry ID (governed contract)", "example": "evid-c9d0e1f2", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "ReestablishReserveResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "reserve", "predecessor_id", "successor_id", "operation" ], "properties": { "reserve": { "$ref": "#/components/schemas/ClaimReserve" }, "predecessor_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "successor_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "operation": { "type": "string", "enum": [ "reestablish" ] } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "ReserveListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimReserve" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "ReserveResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimReserve" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RoleContext": { "type": "object", "required": [ "entity_type", "entity_id" ], "properties": { "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item", "group" ], "description": "The type of entity this role is scoped to. `group` identifies a PartyGroup context while the assignee remains the Party.", "example": "group" }, "entity_id": { "type": "string", "format": "typed-prefix-id", "description": "The identifier of the entity this role is scoped to", "example": "pol_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "RoleTypeListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRoleTypeEntry" }, "example": [ { "code": "policyholder", "display_name": "Policyholder", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true }, { "code": "beneficiary", "display_name": "Beneficiary", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true } ] }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RoleTypeUsageItem": { "type": "object", "required": [ "code", "count" ], "properties": { "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "count": { "type": "integer" } }, "additionalProperties": false }, "RoleTypeUsageListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoleTypeUsageItem" } }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RuleAction": { "type": "object", "required": [ "action_type", "target", "value" ], "properties": { "action_type": { "type": "string", "description": "Type of action to execute.\nCommon types: set_field, emit_event, add_loading, apply_discount,\nreject, approve, escalate, notify.\n", "example": "add_loading" }, "target": { "type": "string", "description": "Target field or entity the action applies to", "example": "premium.young_driver_loading" }, "value": { "description": "Value to set, apply, or emit. Type depends on the action_type.", "example": 0.15 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional parameters for the action", "example": { "reason": "Driver under 25 \u2014 young driver loading applied", "loading_type": "percentage" } } }, "additionalProperties": false }, "RuleCondition": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "Dot-notation path to the field being evaluated", "example": "vehicle.year_of_manufacture" }, "operator": { "type": "string", "description": "Comparison operator to apply.\nCommon operators: eq, ne, gt, gte, lt, lte, in, not_in, contains, matches.\n", "example": "gte" }, "value": { "description": "Value to compare against. Type depends on the field and operator.", "example": 2015 }, "logic": { "type": "string", "nullable": true, "description": "Logical connector to the next condition.\n- and: Both this and the next condition must be true\n- or: Either this or the next condition must be true\nIf omitted on the last condition, defaults to implicit AND with the rule expression.\n", "enum": [ "and", "or" ], "example": "and" } }, "additionalProperties": false }, "RuleEvaluationResult": { "type": "object", "required": [ "rule_id", "rule_name", "outcome", "executed_at" ], "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the rule definition", "example": "rule-fraud-score-v2", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_name": { "type": "string", "description": "Human-readable rule name", "example": "Fraud Probability Score" }, "outcome": { "type": "string", "description": "Rule evaluation outcome (e.g. pass, fail, warn, skip)", "example": "pass" }, "value": { "type": "string", "nullable": true, "description": "Rule evaluation output value (type depends on the rule)", "example": "0.12" }, "error": { "type": "string", "nullable": true, "description": "Error message if rule evaluation failed", "example": null }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was evaluated", "example": "2026-02-18T15:58:00Z" } }, "additionalProperties": false }, "Ruleset": { "type": "object", "required": [ "id", "code", "name", "entity_type", "description", "status", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique ruleset identifier", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Machine-readable code for the ruleset. Used for programmatic reference\nand cross-referencing with product configurations.\n", "example": "motor-comprehensive-v1", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable name for the ruleset", "example": "Motor Vehicle Rating Rules" }, "entity_type": { "type": "string", "enum": [ "claims", "underwriting", "pricing", "claims_assessment", "document_completeness", "discount" ], "description": "The runtime rule lane this ruleset governs. This is not the same closed\nset as platform entity types used on parties, policies, or claims.\n", "example": "pricing" }, "description": { "type": "string", "description": "Detailed description of what this ruleset covers and its purpose", "example": "Validation and pricing rules for comprehensive motor insurance products" }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Lifecycle status of the ruleset.\n- draft: Under development, not yet available for evaluation\n- active: Published and available for evaluation in policy/claim workflows\n- deprecated: Superseded by a newer version; retained for as-was auditability\n", "example": "active" }, "version": { "type": "integer", "minimum": 1, "description": "Monotonically increasing version number. Each modification to rules\ncreates a new version, preserving as-was semantics.\n", "example": 3 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible metadata for the ruleset (e.g. jurisdiction, product line, effective dates)", "example": { "jurisdiction": "US", "product_line": "motor", "effective_from": "2026-01-01" } }, "rules": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BusinessRule" }, "description": "Ordered list of business rules in this ruleset" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\"). Each\nentry explains one element of the ruleset for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated (e.g. a CEL term, a limit, a value_type)." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the ruleset was created", "example": "2026-01-10T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the ruleset was last updated", "example": "2026-03-01T14:30:00Z" } }, "additionalProperties": false }, "RulesetDeleteRuleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Rule deletion returns the canonical success envelope with null data." } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "overall_passed", "results", "rules_count" ], "properties": { "overall_passed": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RulesetEvaluationResult" } }, "rules_count": { "type": "integer", "minimum": 0, "example": 2 } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetEvaluationResult": { "type": "object", "required": [ "rule_id", "rule_name", "passed", "outcome", "message" ], "properties": { "rule_id": { "type": "string", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_name": { "type": "string", "example": "Minimum Driver Age Eligibility" }, "passed": { "type": "boolean", "description": "Whether the rule evaluation passed.", "example": true }, "outcome": { "type": "string", "description": "Runtime evaluation outcome.", "example": "passed" }, "message": { "type": "string", "description": "Empty when the rule succeeded; contains evaluation error detail when available.", "example": "" } }, "additionalProperties": false }, "RulesetListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ruleset" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ruleset" } }, "required": [ "data" ], "additionalProperties": true } ] }, "SingleRuleEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "passed", "outcome", "message" ], "properties": { "passed": { "type": "boolean", "example": true }, "outcome": { "type": "string", "example": "passed" }, "message": { "type": "string", "example": "" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "SubmitClaimRequest": { "type": "object", "required": [ "event_id", "policy_id", "primary_party_id", "description", "claimed_amount", "event_date" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Reference to the insured event", "example": "4cbb0168-4d04-535d-969b-927f53d9c96c", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy under which the claim is submitted", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "primary_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the primary claimant party", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" }, "description": { "type": "string", "description": "Description of the claim circumstances", "example": "Water damage to ground floor following burst pipe. Affected areas include lounge, kitchen, and hallway flooring." }, "claimed_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Total amount being claimed (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "event_date": { "type": "string", "format": "date", "description": "Date when the insured event occurred (ISO 8601 date)", "example": "2026-03-01" }, "priority": { "$ref": "#/components/schemas/ClaimPriority" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for tenant-specific claim data", "example": { "property_address": "15 Bishopsgate, London, EC2N 3AR", "damage_type": "water" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata (integration references, source system info)", "example": { "source_system": "broker-portal", "broker_reference": "BRK-2026-0891" } } }, "additionalProperties": false }, "Subprocessor": { "type": "object", "required": [ "subprocessor_id", "vendor_id", "name", "service_scope", "approval_status" ], "properties": { "subprocessor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique subprocessor identifier", "example": "d3216bd6-21dd-572a-8396-9e1444af9bfb", "x-axiom-identifier-shape": "uuid" }, "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Parent vendor this subprocessor operates under", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Legal or trading name of the subprocessor", "example": "AWS EU West 2 London" }, "service_scope": { "type": "string", "description": "Description of the services the subprocessor provides\nto the parent vendor.\n", "example": "Infrastructure hosting and data storage for policy administration" }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "revoked" ], "description": "Approval status of this subprocessor.\n- pending: Awaiting review and approval\n- approved: Approved for data processing\n- revoked: Previously approved, now revoked\n", "example": "approved" }, "approved_by": { "type": "string", "nullable": true, "readOnly": true, "description": "Identifier of the user who approved this subprocessor", "example": "compliance-officer-001" }, "approved_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "ISO 8601 timestamp when approval was granted", "example": "2026-01-20T11:30:00Z" }, "change_reason": { "type": "string", "nullable": true, "description": "Reason for the most recent status change", "example": "Annual subprocessor review completed \u2014 SOC 2 Type II report verified" } }, "additionalProperties": false }, "SubprocessorDataEnvelope": { "type": "object", "description": "JSON:API single-resource response envelope for a subprocessor", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "$ref": "#/components/schemas/Subprocessor" } }, "additionalProperties": false } }, "additionalProperties": false }, "SuccessEnvelope": { "type": "object", "required": [ "data", "status" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Always the literal string 'success' for successful responses. This invariant is established here and must not be overridden by any operation's response schema." }, "data": { "description": "Operation-specific payload. Overridden per-endpoint via allOf composition (e.g. PartyResponse = allOf:[SuccessEnvelope, {data: Party}]). A caller holding a bare SuccessEnvelope-typed reference sees data as unknown/Any \u2014 hold the op-specific composed type (e.g. PartyResponse) to get the typed data." }, "message": { "type": "string", "description": "Optional human-readable message. Present when supplied by the API." }, "meta": { "type": "object", "description": "Optional response metadata (pagination, request echo). Present when supplied by the API.", "additionalProperties": true }, "links": { "type": "object", "description": "Optional hypermedia links. Present when supplied by the API.", "additionalProperties": true }, "telemetry": { "type": "object", "description": "Response telemetry block under the governed contract. Present on every wrapped success response. Contains timing and trace fields (total_ms, handler_ms, idempotency_replayed, trace_id).", "additionalProperties": true } }, "additionalProperties": true }, "UpdatePartyGroupRequest": { "type": "object", "description": "All fields optional; server updates only those supplied.", "properties": { "display_name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "additionalProperties": false }, "UpdatePartyRequest": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Replacement external identifier. If supplied, the effective source_system must be known and valid.", "example": "BRK-000124", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated party-specific data. Merged with existing attributes.", "example": { "email": "maria.new-email@example.com", "phone": "+46701234567" } }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required when transitioning to status=merged; rejected for non-merged statuses.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "updated_by": { "type": "string", "description": "Identifier of the user or service performing the update", "example": "admin-user-002" } }, "additionalProperties": false }, "UpdateSubprocessorRequest": { "type": "object", "description": "JSON:API envelope for subprocessor update request", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated subprocessor name" }, "service_scope": { "type": "string", "description": "Updated service scope description" }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "revoked" ], "description": "Updated approval status" }, "change_reason": { "type": "string", "description": "Reason for the status change" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "UpdateVendorRequest": { "type": "object", "description": "JSON:API envelope for vendor update request", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "description": "Partial vendor update. Only provided fields are modified.", "properties": { "purpose": { "type": "string", "description": "Updated business purpose" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Updated vendor classification" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Updated data classification labels" }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Updated vendor status" }, "security_review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "rejected" ], "description": "Updated security review status" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/CreateIntegrationInput" }, "description": "Updated integrations list" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "UploadEventDocumentsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ingestAndLinkResultDTO" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "ValidationRule": { "type": "object", "required": [ "rule_type", "value", "error_message" ], "properties": { "rule_type": { "type": "string", "enum": [ "min", "max", "pattern", "required", "oneof" ], "description": "Type of validation to apply.\n- min: Minimum numeric value\n- max: Maximum numeric value\n- pattern: Regular expression the value must match\n- required: Value must be non-empty\n- oneof: Value must be one of a predefined set\n", "example": "min" }, "value": { "description": "The validation constraint value (type depends on rule_type)", "example": 1 }, "error_message": { "type": "string", "description": "Human-readable error message when validation fails", "example": "Policy term must be at least 1 month" } }, "additionalProperties": false }, "Vendor": { "type": "object", "required": [ "vendor_id", "name", "purpose", "classification", "accessed_data_classes", "status", "created_at", "updated_at" ], "properties": { "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique vendor identifier", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional link to a Party record representing this vendor.\nWhen set, the vendor inherits contact and identity data from the Party.\n", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Legal or trading name of the vendor", "example": "CloudSure Technologies (Pty) Ltd" }, "purpose": { "type": "string", "description": "Business purpose for engaging this vendor\n(e.g. claims processing, payment gateway, document storage).\n", "example": "Cloud-based policy administration and document management" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Vendor data-access classification (A-E) under the governed contract.\nHigher letters indicate more restrictive data access.\n", "example": "B" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Data classification labels for data this vendor can access.\nUsed for POPIA/GDPR compliance tracking.\n", "example": [ "personal_identifiable", "financial", "health" ] }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Current lifecycle status of the vendor relationship.\n- draft: Initial vendor record created\n- onboarding: Vendor is being onboarded\n- active: Vendor is approved and operational\n- suspended: Vendor temporarily suspended pending investigation\n- offboarded: Vendor relationship has ended; integrations removed\n", "example": "active" }, "integrations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Integration" }, "description": "System integrations associated with this vendor" }, "security_review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "rejected" ], "nullable": true, "description": "Status of the most recent security review.\n- not_required: No security review needed for this vendor\n- pending: Security review is in progress\n- approved: Security review passed\n- rejected: Security review failed\n", "example": "approved" }, "security_review_approved_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "ISO 8601 timestamp when the security review was approved", "example": "2026-02-15T10:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the vendor record was created", "example": "2025-11-01T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the vendor record was last updated", "example": "2026-03-05T16:20:00Z" } }, "additionalProperties": false }, "VendorDataEnvelope": { "type": "object", "description": "JSON:API single-resource response envelope for a vendor", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "$ref": "#/components/schemas/Vendor" } }, "additionalProperties": false } }, "additionalProperties": false }, "VerifyEvidenceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerifyEvidenceResult" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "VerifyEvidenceResult": { "type": "object", "required": [ "record_id", "content_hash", "status" ], "properties": { "record_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content_hash": { "type": "string" }, "status": { "type": "string", "enum": [ "VERIFIED", "TAMPERED", "MISSING", "CORRECTED" ] }, "details": { "type": "string" } }, "additionalProperties": false }, "VerifyIntegrityResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrityResult" } } }, "additionalProperties": false }, "archiveObjectDTO": { "type": "object", "description": "Archived-object descriptor returned by the archive service Ingest.\nShape is service-defined; common fields documented below.\n", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Archive object identifier.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "object_uri": { "type": "string", "description": "Canonical storage URI." }, "content_hash": { "type": "string", "description": "Content hash of the stored payload." }, "mime_type": { "type": "string" }, "original_filename": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "biTemporalEntryDTO": { "type": "object", "description": "Wire shape for a single bi-temporal catalogue entry.\n\n**id / catalogue_id typed-prefix note:**\n- On createBiTemporalEntry (POST /entries) responses the server renders\n `id` as `cae_` (typed-prefix via renderCatalogueEntryID) and\n `catalogue_id` as `cat_` (typed-prefix via renderCatalogueID).\n- On supersedeBiTemporalEntry (POST /entries/{logical_entry_id}/supersede)\n responses both fields are emitted as raw UUIDs (no renderer applied).\nCallers MUST tolerate both forms when processing response payloads.\n\n**source_provenance_id typed-prefix note:**\n- createBiTemporalEntry renders `source_provenance_id` as `spv_`.\n- supersedeBiTemporalEntry returns the raw UUID string.\n", "required": [ "id", "logical_entry_id", "catalogue_id", "code", "description", "status", "valid_from", "recorded_from", "created_at" ], "properties": { "id": { "type": "string", "description": "Physical row identifier. Rendered as `cae_` on create responses;\nraw UUID on supersede responses (see schema description above).\n", "example": "cae_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "logical_entry_id": { "type": "string", "format": "uuid", "description": "Stable cross-version UUID that groups all bi-temporal versions of the\nsame logical code. Always a raw UUID regardless of operation.\n", "example": "310cf32d-9203-5f14-9574-38c755ef42fa", "x-axiom-identifier-shape": "uuid" }, "catalogue_id": { "type": "string", "description": "Parent catalogue UUID. Rendered as `cat_` on create responses;\nraw UUID on supersede responses (see schema description above).\n", "example": "cat_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "code": { "type": "string", "description": "The canonical lookup code for this entry (e.g. `J18.9`, `703157`).", "example": "J18.9", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "description": { "type": "string", "description": "Human-readable description of the entry.", "example": "Pneumonia, unspecified organism" }, "status": { "type": "string", "description": "Lifecycle status of this entry version (e.g. `active`, `retired`).", "example": "active", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Tenant-defined JSONB attributes for this entry. Shape is catalogue-specific\nand governed by the Catalogue Descriptor's attribute declarations (governed contract).\n" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of the real-world validity window for this entry version (RFC 3339).\n", "example": "2026-01-01T00:00:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "End of the real-world validity window. Omitted when the entry version is\nopen-ended (valid_to IS NULL in storage). Populated after a supersede\noperation closes this version.\n", "example": "2026-12-31T23:59:59Z" }, "recorded_from": { "type": "string", "format": "date-time", "description": "Immutable physical-anchor timestamp (RFC 3339). Set by the persistence-managed records at\nINSERT time; never settable by callers (governed contract recorded_at axis).\n", "example": "2026-01-15T08:00:00Z" }, "source_provenance_id": { "type": "string", "description": "Source-provenance record identifier. Rendered as `spv_` on create\nresponses; raw UUID on supersede responses. Omitted when no provenance\nrecord is linked.\n", "example": "spv_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339).", "example": "2026-01-15T08:00:00Z" } }, "additionalProperties": false }, "biTemporalEntryListResponse": { "type": "object", "x-items-field": "entries", "description": "Envelope for GET /v1/catalogues/{catalogue-ref}/entries list responses.\nKey is `entries` (not `data`) matching the runtime response object{\"entries\": dtos, \"count\": N}\nat runtime source listBiTemporalEntriesHandler.\nx-items-field tells SDK tooling the rows live under `entries`, NOT\n`data`, so consumers do not silently read an empty page. This is an\nAPI 0.1.0 bounded-list exception: `count` only, no page traversal\nparameters and no `has_more`/`next_cursor`, so the reader returns the\none point-in-time page and stops. Use `/entries/history` for\ncursor-paginated full-history traversal.\n", "required": [ "entries", "count" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/biTemporalEntryDTO" }, "description": "Array of matching bi-temporal entry DTOs." }, "count": { "type": "integer", "description": "Total number of entries returned (same as len(entries); not a paged total).", "example": 42 } }, "additionalProperties": false }, "catalogueDTO": { "type": "object", "required": [ "id", "slug", "name", "source", "refresh_frequency", "created_at", "updated_at", "substrate", "has_descriptor" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-assigned UUID (raw UUID, no typed-prefix; runtime source p.ID.String()).", "x-axiom-identifier-shape": "uuid" }, "slug": { "type": "string", "description": "Human-friendly stable identifier used in URL paths (e.g. `icd-10-za`)." }, "name": { "type": "string", "description": "Human-readable display name." }, "source": { "type": "string", "description": "Upstream data authority (e.g. `WHO/DoH-ZA`, `BHF`)." }, "refresh_frequency": { "type": "string", "description": "Declared refresh cadence (e.g. `annual`, `monthly`, `quarterly`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last mutation timestamp (RFC 3339)." }, "substrate": { "type": "string", "enum": [ "bi-temporal" ], "description": "The catalogue's storage substrate. Always `bi-temporal` now that the\nEdition/CatalogueVersion model is retired (governed contract). Surfaced as an\nenum (not a bool) for forward-safety. Lets a client choose its read\npath without probing the retired `GET .../versions` route.\n" }, "has_descriptor": { "type": "boolean", "description": "True when a Catalogue Descriptor (governed contract) is stamped for this\ncatalogue. Pre-resolved via a single batched presence lookup so a\nclient never probes `GET .../descriptor` and reads meaning from a 404.\n" }, "descriptor_id": { "type": "string", "format": "uuid", "description": "The stamped descriptor's row id (raw UUID); omitted when\nhas_descriptor is false.\n", "x-axiom-identifier-shape": "uuid" }, "discarded_at": { "type": "string", "format": "date-time", "description": "Soft-discard timestamp; omitted on live parents." }, "discarded_by": { "type": "string", "description": "Actor identifier that performed the discard; omitted on live parents." }, "discard_reason": { "type": "string", "description": "Human-intelligible discard justification; omitted on live parents." } }, "additionalProperties": false }, "catalogueListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/catalogueDTO" } }, "meta": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "catalogueSingleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/catalogueDTO" } }, "additionalProperties": false }, "eventReportDTO": { "type": "object", "additionalProperties": true, "properties": { "event_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "event": { "$ref": "#/components/schemas/Event" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/ingestAndLinkResultDTO" } }, "document_errors": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "ingestAndLinkResultDTO": { "type": "object", "description": "Result of ingesting one file and linking it to an event/assertion.", "additionalProperties": true, "properties": { "archive_object_id": { "type": "string", "description": "Archive object identifier for the ingested file.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_filename": { "type": "string" }, "mime_type": { "type": "string" } } }, "jobStatusDTO": { "type": "object", "description": "Async job status.\n", "required": [ "id", "kind", "state", "submitted_at", "attempt", "max_attempts" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Job UUID.", "x-axiom-identifier-shape": "uuid" }, "kind": { "type": "string", "description": "Work type (e.g. `catalogue.ingest`)." }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "dead_letter" ], "description": "Current job state." }, "submitted_at": { "type": "string", "format": "date-time", "description": "Submission timestamp (RFC 3339)." }, "claimed_at": { "type": "string", "format": "date-time", "description": "When a worker claimed the job (RFC 3339). Omitted until claimed." }, "completed_at": { "type": "string", "format": "date-time", "description": "Terminal-state timestamp (RFC 3339). Omitted until terminal." }, "attempt": { "type": "integer", "description": "Current attempt number." }, "max_attempts": { "type": "integer", "description": "Maximum attempts before dead-lettering." }, "correlation_id": { "type": "string", "description": "Correlation id threaded through the job. Omitted when unset.", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "last_error": { "$ref": "#/components/schemas/jobStatusError" }, "error": { "$ref": "#/components/schemas/jobStatusError" }, "progress": { "$ref": "#/components/schemas/jobStatusProgress" } }, "additionalProperties": false }, "jobStatusError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "x-axiom-coded-value-classification": "platform-error-code" }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": false }, "jobStatusProgress": { "type": "object", "required": [ "completed_units" ], "properties": { "completed_units": { "type": "integer", "format": "int64", "description": "Units of work completed so far." }, "total_units": { "type": "integer", "format": "int64", "description": "Total units of work, when known. Omitted when indeterminate." }, "message": { "type": "string", "description": "Free-text progress message." }, "last_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last progress update (RFC 3339)." } }, "additionalProperties": false }, "jobStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/jobStatusDTO" } }, "additionalProperties": false }, "objectUploadInitiateDTO": { "type": "object", "description": "Presigned-upload coordinates.\n", "required": [ "upload_id", "put_url", "object_uri", "expires_at" ], "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Server-assigned upload identifier, referenced in downstream ingest calls.", "example": "310cf32d-9203-5f14-9574-38c755ef42fa", "x-axiom-identifier-shape": "uuid" }, "put_url": { "type": "string", "description": "Presigned PUT URL \u2014 upload the raw bytes here with HTTP PUT." }, "object_uri": { "type": "string", "description": "Canonical storage URI (managed-object://redacted context/upload_id)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry of the presigned URL (RFC 3339); typically 1 hour from issue." } }, "additionalProperties": false }, "objectUploadInitiateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/objectUploadInitiateDTO" } }, "additionalProperties": false }, "replacementActor": { "type": "object", "required": [ "actor_type", "actor_id", "actor_original_id" ], "properties": { "actor_type": { "type": "string", "description": "Actor type (e.g. `human`, `service`)." }, "actor_id": { "type": "string", "description": "Actor identifier (typed-prefix wire form).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "actor_original_id": { "type": "string", "description": "Original (pre-merge) actor identifier for audit continuity.", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "replacementAdvanceRequest": { "type": "object", "required": [ "actor", "reason", "occurred_at", "evidence_payload", "version" ], "properties": { "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible justification for the advance." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "evidence_payload": { "type": "object", "additionalProperties": true, "description": "Step-specific evidence required to advance." }, "version": { "type": "integer", "description": "Optimistic-concurrency version of the workflow being advanced." } }, "additionalProperties": false }, "replacementCancelRequest": { "type": "object", "required": [ "actor", "reason", "occurred_at", "version" ], "properties": { "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible cancellation justification." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "version": { "type": "integer", "description": "Optimistic-concurrency version of the workflow being cancelled." } }, "additionalProperties": false }, "replacementDTO": { "type": "object", "description": "Replacement workflow state.\n", "required": [ "id", "policy_id", "existing_policy_ids", "jurisdiction_code", "state", "allowed_transitions", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Replacement workflow id (prp_ typed-prefix).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "description": "Replacement policy id.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "existing_policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Superseded policy ids." }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code (lowercase ISO 3166-1 alpha-2)." }, "state": { "type": "string", "description": "Current workflow step/state.", "x-axiom-coded-value-classification": "tenant-lifecycle-state" }, "config_pack_version_id": { "type": "string", "description": "Config-pack version governing this workflow's rules.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "step_evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Per-step evidence reference ids." }, "step_timestamps": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "Per-step transition timestamps." }, "transition_history": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ordered transition records." }, "allowed_transitions": { "type": "array", "items": { "type": "string" }, "description": "Transitions permitted from the current state." }, "explanation_tree_id": { "type": "string", "description": "Explanation-tree id for this decision (governed contract). Omitted when unset.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.22 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "version": { "type": "integer", "description": "Optimistic-concurrency version." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "time_gate_info": { "type": "object", "description": "Present when the next step is time-gated.", "properties": { "step_name": { "type": "string" }, "min_wait_duration": { "type": "string" }, "earliest_advance": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false }, "replacementEvidenceDTO": { "type": "object", "required": [ "replacement_id", "step_evidence", "evidence_order" ], "properties": { "replacement_id": { "type": "string", "format": "uuid", "description": "Replacement workflow UUID.", "x-axiom-identifier-shape": "uuid" }, "step_evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Per-step evidence reference ids." }, "evidence_order": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of step names in evidence-collection order." } }, "additionalProperties": false }, "replacementEvidenceResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/replacementEvidenceDTO" } }, "additionalProperties": false }, "replacementInitiateRequest": { "type": "object", "required": [ "policy_id", "existing_policy_ids", "jurisdiction_code", "actor", "reason", "occurred_at" ], "properties": { "policy_id": { "type": "string", "description": "The replacement policy id (typed-prefix wire form).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "existing_policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Policies being superseded by this replacement." }, "jurisdiction_code": { "type": "string", "description": "ISO 3166-1 alpha-2 jurisdiction code (lowercase)." }, "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible justification (audit trail)." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional caller-supplied metadata." } }, "additionalProperties": false }, "replacementSingleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/replacementDTO" } }, "additionalProperties": false } }, "responses": { "BadRequest": { "description": "**400 Bad Request**\n\nThe request was malformed or contained invalid parameters.\n\nCommon causes:\n- Missing required parameter\n- Invalid parameter format\n- Invalid JSON syntax\n- Unsupported content type\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_parameter": { "summary": "Missing required parameter", "value": { "errors": [ { "status": "400", "code": "MISSING_PARAMETER", "title": "Bad Request", "detail": "Required parameter 'tenant context' is missing", "source": { "parameter": "tenant context" } } ] } }, "invalid_uuid": { "summary": "Invalid UUID format", "value": { "errors": [ { "status": "400", "code": "INVALID_PARAMETER", "title": "Bad Request", "detail": "Parameter 'id' must be a valid UUID", "source": { "parameter": "id" } } ] } } } } } }, "Conflict": { "description": "**409 Conflict**\n\nThe request conflicts with the current state of the resource.\n\nCommon causes:\n- Attempting to create a duplicate resource\n- Optimistic locking failure (stale version)\n- Invalid state transition\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicate": { "summary": "Duplicate resource", "value": { "errors": [ { "status": "409", "code": "DUPLICATE_RESOURCE", "title": "Conflict", "detail": "A policy with this number already exists" } ] } }, "version_conflict": { "summary": "Version conflict", "value": { "errors": [ { "status": "409", "code": "OPTIMISTIC_LOCK_FAILURE", "title": "Conflict", "detail": "Resource was modified by another request. Please refresh and try again.", "meta": { "current_version": 5, "provided_version": 3 } } ] } } } } } }, "Forbidden": { "description": "**403 Forbidden**\n\nThe authenticated user does not have permission to perform this action.\n\nCommon causes:\n- Insufficient role permissions\n- Accessing another tenant's resource\n- Resource-level access control denial\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "errors": [ { "status": "403", "code": "INSUFFICIENT_PERMISSIONS", "title": "Forbidden", "detail": "You do not have permission to perform this action" } ] } }, "tenant_access": { "summary": "Tenant access denied", "value": { "errors": [ { "status": "403", "code": "TENANT_ACCESS_DENIED", "title": "Forbidden", "detail": "You are not authorized to access this tenant's resources" } ] } } } } } }, "InternalError": { "description": "**500 Server Error**\n\nAn unexpected error occurred. The correlation ID can be used\nfor support inquiries.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "500", "code": "SERVER_ERROR", "title": "Server Error", "detail": "An unexpected error occurred. Please try again later.", "meta": { "correlation_id": "req-abc-123-def-456" } } ] } } } }, "NotFound": { "description": "**404 Not Found**\n\nThe requested resource was not found.\n\nNote: For security, we return 404 instead of 403 when the user\nis not authorized to know whether the resource exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "errors": [ { "status": "404", "code": "RESOURCE_NOT_FOUND", "title": "Not Found", "detail": "The requested policy was not found" } ] } }, "endpoint_not_found": { "summary": "Endpoint not found", "value": { "errors": [ { "status": "404", "code": "ENDPOINT_NOT_FOUND", "title": "Not Found", "detail": "The requested endpoint does not exist" } ] } } } } } }, "ServiceUnavailable": { "description": "**503 Service Unavailable**\n\nThe service is temporarily unavailable. Usually due to\nmaintenance or high load.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "503", "code": "SERVICE_UNAVAILABLE", "title": "Service Unavailable", "detail": "The service is temporarily unavailable. Please try again later.", "help_url": "https://developers.afr-dev.axiom.express/api/reference/0.1.22/errors/SERVICE_UNAVAILABLE/", "meta": { "retry_after": 30 } } ] } } } }, "TooManyRequests": { "description": "**429 Too Many Requests**\n\nRate limit exceeded. Retry after the specified period.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Limit": { "description": "Request limit per time window", "schema": { "type": "integer", "example": 1000 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit resets", "schema": { "type": "integer", "example": 1707307200 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "429", "code": "RATE_LIMITED", "title": "Too Many Requests", "detail": "Rate limit exceeded. Please retry after 60 seconds.", "help_url": "https://developers.afr-dev.axiom.express/api/reference/0.1.22/errors/RATE_LIMITED/", "meta": { "retry_after": 60 } } ] } } } }, "Unauthorized": { "description": "**401 Unauthorized**\n\nAuthentication is required but was not provided or is invalid.\n\nCommon causes:\n- Missing Authorization header\n- Invalid or expired token\n- Malformed credentials\n", "headers": { "WWW-Authenticate": { "description": "Authentication challenge", "schema": { "type": "string", "example": "Bearer realm=\"axiom\", error=\"invalid_token\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_auth": { "summary": "Missing authentication", "value": { "errors": [ { "status": "401", "code": "AUTHENTICATION_REQUIRED", "title": "Unauthorized", "detail": "Authentication is required to access this resource" } ] } }, "expired_token": { "summary": "Expired token", "value": { "errors": [ { "status": "401", "code": "TOKEN_EXPIRED", "title": "Unauthorized", "detail": "The provided authentication token has expired" } ] } } } } } }, "ValidationError": { "description": "**422 Unprocessable Entity**\n\nThe request was well-formed but contained semantic errors.\n\nCommon causes:\n- Field validation failures\n- Business rule violations\n- Invalid state transitions\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "single_field": { "summary": "Single field validation", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'email' must be a valid email address", "source": { "pointer": "/data/attributes/email" } } ] } }, "multiple_fields": { "summary": "Multiple validation errors", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'start_date' is required", "source": { "pointer": "/data/attributes/start_date" } }, { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'premium' must be greater than 0", "source": { "pointer": "/data/attributes/premium" } } ] } }, "business_rule": { "summary": "Business rule violation", "value": { "errors": [ { "status": "422", "code": "BUSINESS_RULE_VIOLATION", "title": "Validation Error", "detail": "Policy end date must be after start date" } ] } } } } } } } }, "x-axiom-schema-contract": { "schema_version": "axiom.public-schema-contract.v1", "posture": "classified-alpha-baseline", "component_schema_count": 256, "object_shape": { "closed_object_count": 196, "open_extension_object_count": 179, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 1, "format_constrained_id_count": 128, "classified_id_string_count": 130, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 12, "classified_money_like_count": 1, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 107, "classified_code_string_count": 35, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }