{ "openapi": "3.0.3", "info": { "title": "Axiom API 0.1.1 - Policies", "description": "Product, policy, quote, and policy lifecycle operations.", "version": "0.1.1", "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": "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": "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": "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." } } ], "paths": { "/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.1 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.1 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.1 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.1 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.1 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}/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.1 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.1 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-wire-success-profile": "json-api", "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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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": "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.1 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.1 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-wire-success-profile": "json-api", "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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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": "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.1 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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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}/endorsements": { "post": { "operationId": "createEndorsement", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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": "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.1 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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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": "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.1 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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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", "x-axiom-wire-success-profile": "json-api", "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.1 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.1 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": "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.1 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.1 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.1 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-wire-success-profile": "json-api", "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": "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.1 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" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "parameters": { "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." }, "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.1 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)." } }, "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 }, "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 }, "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.1 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.1 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.1 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 } ] }, "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.1 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 } ] }, "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 }, "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.1 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 } ] }, "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.1 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.1 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.1 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 }, "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.1/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.1 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.1 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 }, "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 }, "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 }, "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 }, "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.1 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.1 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.1 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.1 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.1 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.1 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 } ] }, "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.1 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.1 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.1 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.1 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.1 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.1 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.1 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.1 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.1 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 } } }, "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.1 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.1 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.1 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.1 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.1 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.1 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 } ] }, "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 }, "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 }, "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.1 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.1 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.1 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.1 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.1/errors/SERVICE_UNAVAILABLE/", "meta": { "retry_after": 30 } } ] } } } }, "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": 68, "object_shape": { "closed_object_count": 62, "open_extension_object_count": 53, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 0, "format_constrained_id_count": 21, "classified_id_string_count": 49, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 0, "classified_money_like_count": 0, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 26, "classified_code_string_count": 15, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }