{ "openapi": "3.0.3", "info": { "title": "Axiom API 0.1.1 - Claims", "description": "Claim list, claim detail, claim document, reserve, recovery, and claim workflow 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": "Claim", "description": "Claims processing \u2014 submission, assessment, payment, and closure.\nStatus: submitted \u2192 assessing \u2192 assessed \u2192 approved \u2192 paying \u2192 paid \u2192 closed.\nAlso: submitted \u2192 rejected \u2192 closed.\nDeprecated (RFC-8594; Sunset 2026-08-31) in favour of Assertion.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } } ], "paths": { "/v1/claims": { "post": { "operationId": "submitClaim", "x-axiom-wire-success-profile": "json-api", "summary": "Submit a new claim", "description": "Submit an insurance claim against a policy. The claim is created in \"submitted\"\nstatus and enters the claims workflow for assessment.\n\nThe referenced policy must be active (or within its coverage period for the\nevent date). The event must fall within the policy's effective period.\n\nThe system validates coverage eligibility, checks for duplicate claims, and\ntriggers any configured automated rules (e.g. fraud scoring).\n\nSide effects: persists the claim in submitted status; initiates the claims workflow (automated triage and assessment assignment); emits an audit entry recording the submission.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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/SubmitClaimRequest" }, "examples": { "motor_accident": { "summary": "Motor accident claim", "value": { "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "description": "Rear-end collision at intersection of 5th Avenue and 42nd Street, New York. Third-party vehicle damage and whiplash injury to driver.", "claimed_amount": { "amount_minor": 8500000, "currency_code": "zar" }, "event_date": "2026-03-01", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567", "third_party_involved": true }, "metadata": { "source_system": "mobile-app", "reporter_reference": "APP-2026-0042" } } }, "property_water_damage": { "summary": "Property water damage claim (UK)", "value": { "event_id": "40726a06-5c87-5675-a57a-31805ea70e14", "policy_id": "75e1ccb2-5983-5aa7-9ba3-5a6cd095bd47", "primary_party_id": "ab18f8ca-0aca-5cf3-abe4-5e99c50d684e", "description": "Burst pipe in upstairs bathroom caused extensive water damage to ground floor. Affected areas include lounge ceiling, kitchen units, and hallway flooring.", "claimed_amount": { "amount_minor": 4500000, "currency_code": "gbp" }, "event_date": "2026-02-28", "priority": "high", "attributes": { "property_address": "14 Elm Grove, Bristol, BS8 1TB", "damage_type": "water", "emergency_repairs_done": true }, "metadata": { "source_system": "broker-portal", "broker_reference": "BRK-2026-0891" } } }, "health_hospitalisation": { "summary": "Health hospitalisation claim (Nigeria)", "value": { "event_id": "75e1ccb2-5983-5aa7-9ba3-5a6cd095bd47", "policy_id": "ab18f8ca-0aca-5cf3-abe4-5e99c50d684e", "primary_party_id": "9d590f8b-2e0e-5050-9dfa-f7a1ffcb1569", "description": "Emergency appendectomy at Lagos University Teaching Hospital. Admitted via A&E, surgery performed same day, 3-night stay.", "claimed_amount": { "amount_minor": 120000000, "currency_code": "ngn" }, "event_date": "2026-03-05", "priority": "urgent", "attributes": { "hospital_name": "Lagos University Teaching Hospital", "admission_type": "emergency", "procedure_code": "47.09" }, "metadata": { "source_system": "hospital-integration", "pre_auth_reference": "PA-2026-LUTH-0088" } } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Dual-mode claim submission with documents. The `claim_data` field\ncarries a JSON object (as a string) matching SubmitClaimRequest;\nany additional file parts are ingested as archive attachments.\n", "required": [ "claim_data" ], "properties": { "claim_data": { "type": "string", "description": "JSON object (as a string) matching SubmitClaimRequest." } }, "additionalProperties": { "type": "string", "format": "binary" } } } } }, "responses": { "201": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" }, "examples": { "claim_submitted": { "summary": "Motor claim submitted", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "submitted", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-12T08:00:00Z", "total_claimed_amount": 8500000, "description": "Rear-end collision at intersection of 5th Avenue and 42nd Street", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567" }, "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Claim submitted successfully", "telemetry": { "total_ms": 42, "handler_ms": 38, "trace_id": "abc123" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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": "listClaims", "x-axiom-wire-success-profile": "json-api", "summary": "List claims", "description": "Retrieve a cursor-paginated list of claims for the tenant.\nResults are sorted by created_at descending with id as a stable tie-breaker.\nSort order is not configurable.\n\nReturns claims across all statuses (submitted, under_review, assessed,\npartial_approval, denied, paid, closed).\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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 claims to return in this page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page.\nDo not construct or modify this value.\n" }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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 claims against this policy.\nAccepts the canonical typed-prefix policy id (`pol_\u2026`, governed contract).\nA malformed value returns 400. Absent = all claims for the tenant\n(current behaviour). Composes with the existing operating-tenant tenant-isolated\nscope; never widens it.\n" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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 claims whose primary party is this party\n(`primary_party_id`). Accepts the canonical typed-prefix party id\n(`pty_\u2026`, governed contract). A malformed value returns 400. Absent = all claims\nfor the tenant (current behaviour). Composes with the existing\noperating-tenant tenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Claims retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimListResponse" }, "examples": { "claims_list": { "summary": "Claims across statuses", "value": { "data": [ { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "under_review", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-02T09:00:00Z", "total_claimed_amount": 8500000, "description": "Motor accident \u2014 rear-end collision", "priority": "medium", "created_at": "2026-03-02T09:00:00Z", "updated_at": "2026-03-05T14:00:00Z" }, { "id": "1622e4e4-3099-5794-a127-5c7103afaabf", "claim_number": "CLM-2026-00041", "event_id": "6e2f41e0-f63e-5a20-a76b-0c1f296d9db7", "policy_id": "3cce17f2-f5d3-586a-9b26-50ee6428c9fb", "status": "paid", "primary_party_id": "9e3927be-a1c5-5309-be43-63195769f557", "event_date": "2026-02-15T00:00:00Z", "reported_date": "2026-02-16T10:00:00Z", "total_claimed_amount": 1250000, "description": "Theft of laptop and camera equipment from vehicle", "priority": "low", "created_at": "2026-02-16T10:00:00Z", "updated_at": "2026-03-01T16:00:00Z" } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMi0xNlQxMDowMDowMFoiLCJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS1iY2RlLTIzNDU2Nzg5MDEyMyJ9" }, "status": "success", "telemetry": { "total_ms": 18, "handler_ms": 14, "trace_id": "def456" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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": [ "policy_id", "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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/claims/{id}": { "get": { "operationId": "getClaim", "x-axiom-wire-success-profile": "json-api", "summary": "Get a claim by ID", "description": "Retrieve a single claim with its full details including claim items,\nassessments, payments, and current workflow state.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "Claim retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" }, "examples": { "assessed_claim": { "summary": "Assessed motor claim with items and assessment", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "assessed", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-02T09:00:00Z", "total_claimed_amount": 8500000, "description": "Rear-end collision at intersection", "priority": "medium", "attributes": { "loss_location": "Manhattan, New York", "police_case_number": "NYPD-2026-MN-4567" }, "claim_items": [ { "id": "32798e17-3851-562c-b192-f49109f3465d", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "item_type": "vehicle_damage", "description": "Rear bumper replacement and respray", "claimed_amount": { "amount_minor": 5500000, "currency_code": "zar" }, "approved_amount": { "amount_minor": 5200000, "currency_code": "zar" }, "status": "approved", "created_at": "2026-03-02T09:00:00Z" }, { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "item_type": "medical", "description": "Physiotherapy for whiplash \u2014 6 sessions", "claimed_amount": { "amount_minor": 3000000, "currency_code": "zar" }, "approved_amount": { "amount_minor": 2800000, "currency_code": "zar" }, "status": "approved", "created_at": "2026-03-02T09:00:00Z" } ], "assessments": [ { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "assessment_type": "initial", "assessed_by": "assessor-jvd-001", "assessed_at": "2026-03-08T16:00:00Z", "status": "approved", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "notes": "Damage consistent with reported collision. Approved less R5,000 policy excess." } ], "created_at": "2026-03-02T09:00:00Z", "updated_at": "2026-03-08T16:00:00Z" }, "status": "success", "telemetry": { "total_ms": 22, "handler_ms": 18, "trace_id": "ghi789" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/assess": { "post": { "operationId": "assessClaim", "x-axiom-wire-success-profile": "json-api", "summary": "Assess a claim", "description": "Submit an assessment for a claim. Assessments record the outcome of\ninvestigation and evaluation, including approved amounts and per-item\nassessments.\n\nThe claim must be in \"under_review\" status. After assessment, the claim\ntransitions to \"assessed\" (full approval), \"partial_approval\", or \"denied\".\n\nAutomated rule evaluation results (e.g. fraud scoring) are included in the\nassessment record for audit and explainability.\n\nSide effects: returns the assessment result with the claim status transitioned (under_review to assessed, partial_approval, or denied) without persisting the changes. Emits an audit entry when audit is configured.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessClaimRequest" }, "examples": { "approve_motor": { "summary": "Approve motor claim with excess deduction", "value": { "assessed_by": "assessor-jvd-001", "assessment_notes": "Site inspection completed. Damage verified against police report and repair quotations from two panel beaters. Approved less R5,000 policy excess.", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "item_assessments": [ { "item_id": "32798e17-3851-562c-b192-f49109f3465d", "approved_amount": { "amount_minor": 5200000, "currency_code": "zar" }, "notes": "Panel beater quotation verified. Original parts specified." }, { "item_id": "047a5bdd-844c-502f-993a-b05e907ca746", "approved_amount": { "amount_minor": 2800000, "currency_code": "zar" }, "notes": "Physiotherapy approved per medical protocol for whiplash grade II" } ], "metadata": { "inspection_date": "2026-03-06", "photos_reviewed": 18 } } }, "deny_claim": { "summary": "Deny a fraudulent claim", "value": { "assessed_by": "assessor-senior-002", "assessment_notes": "Investigation revealed older damage inconsistent with reported event date. GPS data contradicts reported location. Claim denied under policy exclusion clause 7.2 (material misrepresentation).", "metadata": { "investigation_type": "fraud", "external_report_reference": "INV-2026-0033" } } } } } } }, "responses": { "200": { "description": "Claim assessed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessClaimResponse" }, "examples": { "assessment_recorded": { "summary": "Assessment with rule evaluation results", "value": { "data": { "id": "047a5bdd-844c-502f-993a-b05e907ca746", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "assessment_type": "initial", "assessed_by": "assessor-jvd-001", "assessed_at": "2026-03-08T16:00:00Z", "status": "approved", "approved_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "notes": "Damage verified against police report and repair quotations", "rule_results": [ { "rule_id": "rule-fraud-score-v2", "rule_name": "Fraud Probability Score", "outcome": "pass", "value": "0.08", "executed_at": "2026-03-08T15:58:00Z" }, { "rule_id": "rule-coverage-check-v1", "rule_name": "Coverage Eligibility Check", "outcome": "pass", "value": "true", "executed_at": "2026-03-08T15:58:01Z" } ] }, "assessment": [ { "rule_id": "rule-fraud-score-v2", "outcome": "pass" }, { "rule_id": "rule-coverage-check-v1", "outcome": "pass" } ], "status": "success", "message": "Claim assessed successfully using tenant-specific adjudication rules", "telemetry": { "total_ms": 95, "handler_ms": 88, "trace_id": "jkl012" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failure. Codes: INVALID_STATE_TRANSITION,\nINVALID_MONETARY_AMOUNT.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "Invalid state transition", "value": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Invalid State Transition", "detail": "Claim must be under_review to be assessed, current status: paid" } ] } }, "invalid_amount": { "summary": "Invalid monetary amount", "value": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "approved_amount must be a non-negative integer in cents" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/authorisations": { "post": { "operationId": "recordClaimAuthorisation", "x-axiom-wire-success-profile": "json-api", "summary": "Record a claim authorisation", "description": "Record an governed contract authorisation sub-event against a claim. The row is\nappend-only and carries the authorising actor, authorised scope, budget,\ngoverning-version binding, optional compliance state, decision date, and\nexplanation-node reference.\n\nClaim payments may cite the returned authorisation id. When they do, the\npayment path runs the authorisation compliance gate before disbursement.\n\nSide effects: persists an `authorisation_transitions` row under the\ntenant context and returns the recorded authorisation.\n", "tags": [ "Claim" ], "security": [ { "BearerAuth": [ "claims:authorise" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationRequest" }, "examples": { "medical_pre_auth": { "summary": "Medical service authorisation", "value": { "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "budget_minor": 250000, "budget_currency_code": "zar", "governing_version_kind": "catalogue", "governing_version_row_id": "b1468ab8-97c1-5aa6-aca6-9430e182a5bd", "decision_date": "2026-07-06T10:00:00Z", "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346" } } } } } }, "responses": { "201": { "description": "Claim authorisation recorded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationResponse" }, "examples": { "recorded": { "summary": "Recorded authorisation", "value": { "data": { "id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "logical_authorisation_id": "a1699eac-cf08-52d7-be4d-242049b373f5", "entity_type": "claim", "entity_id": "07805e66-69d7-5b42-a978-32729404b560", "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "budget_minor": 250000, "budget_currency_code": "zar", "decision_date": "2026-07-06T10:00:00Z", "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346", "valid_from": "2026-07-06T10:00:00Z", "asserted_from": "2026-07-06T10:00:00Z" }, "status": "success", "message": "Claim authorisation recorded successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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": [ "claims:authorise" ], "required_permissions": [ "claims:authorise" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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/claims/{id}/pay": { "post": { "operationId": "payClaim", "x-axiom-wire-success-profile": "json-api", "summary": "Process a claim payment", "description": "Initiate payment for an assessed claim. The claim must be in \"assessed\"\nor \"partial_approval\" status before payment can be processed.\n\nPayment is recorded against the claim and linked to the billing/payments\nsubsystem. The claim transitions to \"paid\" once the payment is confirmed.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nSide effects: returns the constructed payment record and ledger entries with the claim status transitioned to paid, without persisting the changes. Emits an audit entry when audit is configured.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayClaimRequest" }, "examples": { "bank_transfer": { "summary": "Pay claim via bank transfer", "value": { "paid_amount": { "amount_minor": 8000000, "currency_code": "zar" }, "payment_method": "bank_transfer", "payment_notes": "Final settlement \u2014 approved amount less policy excess", "processed_by": "payments-officer-mk-003", "metadata": { "bank_reference": "JPMC-ACH-2026030801", "beneficiary_account": "****4521", "beneficiary_bank": "JPMorgan Chase" } } }, "direct_settlement": { "summary": "Direct settlement to service provider (health)", "value": { "paid_amount": { "amount_minor": 115000000, "currency_code": "ngn" }, "payment_method": "direct_settlement", "payment_notes": "Direct settlement to hospital per authorisation reference PA-2026-LUTH-0088", "processed_by": "claims-auto-pay", "authorisation_id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "metadata": { "provider_reference": "LUTH-INV-2026-4455", "pre_auth_reference": "PA-2026-LUTH-0088" } } } } } } }, "responses": { "200": { "description": "Payment processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayClaimResponse" }, "examples": { "payment_processed": { "summary": "Payment confirmed", "value": { "data": { "id": "1724e0cd-6c5f-5bc3-a252-3e03f4c4a43b", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "payment_id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount_paid": { "amount_minor": 8000000, "currency_code": "zar" }, "payment_method": "bank_transfer", "processed_at": "2026-03-10T10:00:00Z", "processed_by": "payments-officer-mk-003", "status": "completed", "authorisation_id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "authorisation_gate_outcome": "clear" }, "ledger_entries": [ { "id": "b02b9190-8861-571a-9c77-e5ca374c70b7", "type": "claim_payment", "amount_minor": 8000000 } ], "status": "success", "message": "Claim payment processed successfully", "telemetry": { "total_ms": 64, "handler_ms": 58, "trace_id": "mno345" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failure. Codes: INVALID_STATE_TRANSITION,\nINVALID_MONETARY_AMOUNT, AUTHORISATION_PAYMENT_BLOCKED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_state": { "summary": "Invalid state transition", "value": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Invalid State Transition", "detail": "Claim must be assessed or partial_approval to process payment, current status: under_review" } ] } }, "invalid_amount": { "summary": "Invalid monetary amount", "value": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "paid_amount must be a positive integer in cents" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/close": { "post": { "operationId": "closeClaim", "x-axiom-wire-success-profile": "json-api", "summary": "Close a claim", "description": "Close a claim, marking its lifecycle as complete. Claims can be closed after\npayment has been disbursed, or without payment if denied or withdrawn.\n\nClosing a claim is an irreversible action. Once closed, no further assessments\nor payments can be made against the claim.\n\nThe claim must be in one of: \"paid\", \"denied\", or \"assessed\" status.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nSide effects: persists the claim in closed status; emits an audit entry recording the closure.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "closure_reason": { "type": "string", "description": "Reason for closing the claim", "example": "Final settlement disbursed and accepted by claimant" }, "closed_by": { "type": "string", "description": "Identifier of the user or system closing the claim", "example": "claims-manager-001" } }, "additionalProperties": false }, "examples": { "paid_closure": { "summary": "Close after payment", "value": { "closure_reason": "Final settlement disbursed and accepted by claimant", "closed_by": "claims-manager-001" } }, "withdrawn": { "summary": "Close due to withdrawal", "value": { "closure_reason": "Claimant withdrew the claim on 2026-03-10", "closed_by": "claims-officer-015" } } } } } }, "responses": { "200": { "description": "Claim closed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" }, "examples": { "claim_closed": { "summary": "Claim after closure", "value": { "data": { "id": "07805e66-69d7-5b42-a978-32729404b560", "claim_number": "CLM-2026-00042", "event_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "status": "closed", "primary_party_id": "90ea0de6-41a6-5bff-b66b-7dbbf93ba420", "event_date": "2026-03-01T00:00:00Z", "reported_date": "2026-03-02T09:00:00Z", "total_claimed_amount": 8500000, "description": "Rear-end collision at intersection", "priority": "medium", "created_at": "2026-03-02T09:00:00Z", "updated_at": "2026-03-12T14:00:00Z" }, "status": "success", "message": "Claim closed successfully", "telemetry": { "total_ms": 31, "handler_ms": 27, "trace_id": "pqr678" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Claim not in a closeable state (INVALID_STATE_TRANSITION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_STATE_TRANSITION", "title": "Validation Error", "detail": "Claim cannot perform close from status submitted" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Not implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "SERVER_ERROR", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/pdf": { "get": { "operationId": "generateClaimPDF", "summary": "Generate a claim PDF report", "description": "Generate a PDF document summarising the claim, including the event details,\nassessment results, payment information, and workflow history.\n\nThe PDF is generated on demand and returned as a binary response. For large\nclaims with extensive documentation, generation may take several seconds.\n\nThe generated PDF includes:\n- Claim header (claim number, policy number, status)\n- Event details and description\n- Claim items with amounts\n- Assessment summary and notes\n- Payment details (if applicable)\n- Workflow timeline\n\nThis endpoint returns binary PDF data (application/pdf), not a JSON envelope.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "PDF generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded PDF", "schema": { "type": "string", "example": "attachment; filename=\"CLM-2026-00042.pdf\"" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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/claims/{id}/reserves": { "post": { "operationId": "createReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Create a claim reserve", "description": "Create a new active reserve for a claim. The amount must be a positive\ninteger in cents. On success the reserve is created with state \"active\",\ncurrent_amount == initial_amount, and released_amount == 0.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reserve_type", "amount" ], "properties": { "reserve_type": { "type": "string", "example": "case_estimate" }, "amount": { "type": "integer", "format": "int64", "example": 500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string", "example": "initial case estimate" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Reserve created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "description": "Validation error (zero or negative amount)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_MONETARY_AMOUNT", "title": "Invalid Monetary Amount", "detail": "initial_amount must be a positive integer in cents" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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": "listClaimReserves", "x-axiom-wire-success-profile": "json-api", "summary": "List reserves for a claim", "description": "Retrieve all reserves for a claim, ordered by established_at descending.\nReturns explanation-ready reserve facts.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "Reserves retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveListResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/reserves/{reserveId}": { "get": { "operationId": "getReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Get a single reserve", "description": "Retrieve a single reserve by ID with explanation-ready facts.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "responses": { "200": { "description": "Reserve retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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" } }, "patch": { "operationId": "updateReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Update an active reserve", "description": "Only reserves in \"active\" state can be updated.", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 600000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/reserves/{reserveId}/release": { "post": { "operationId": "releaseReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Release reserve amount", "description": "Partial release yields \"partially_released\"; full release yields\n\"fully_released\". Over-release returns HTTP 422.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 300000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Over-release or invalid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/reserves/{reserveId}/cancel": { "post": { "operationId": "cancelReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Cancel an active reserve", "description": "Only reserves in \"active\" state can be cancelled. Returns inactive\nreserve with zero remaining exposure.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Reserve cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveResponse" } } } }, "422": { "description": "Reserve not in active state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{id}/reserves/{reserveId}/reestablish": { "post": { "operationId": "reestablishReserve", "x-axiom-wire-success-profile": "json-api", "summary": "Re-establish a terminal reserve", "description": "Create a new active reserve linked to a terminal predecessor.\nRe-establishment from \"active\" or \"partially_released\" is rejected.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" }, { "name": "reserveId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique reserve identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 750000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Reserve re-established", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReestablishReserveResponse" } } } }, "422": { "description": "Reserve not terminal or invalid amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/reserves": { "get": { "operationId": "listPolicyReserves", "x-axiom-wire-success-profile": "json-api", "summary": "List reserves by policy", "description": "policy_id query parameter is required.", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "policy_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Reserves retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveListResponse" } } } }, "400": { "description": "Missing policy_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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": [ "policy_id", "active_only" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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/claims/{id}/investigations": { "post": { "operationId": "createOrAdvanceInvestigation", "x-axiom-wire-success-profile": "json-api", "summary": "Create or advance an SIU investigation", "description": "Create a new SIU investigation on a claim, or advance an existing open\ninvestigation by exactly one state. The endpoint uses create-or-advance\nsemantics: the first POST with `target_state=assigned` creates the\ninvestigation (HTTP 201); subsequent POSTs advance the open investigation\n(HTTP 200).\n\nState machine: assigned \u2192 investigating \u2192 findings_submitted \u2192 closed.\nDisposition (substantiated|unsubstantiated|settled) is required only when\n`target_state=closed`.\n\n`settled` closes the SIU investigation only \u2014 it does not change claim\nstatus, create recovery, or affect normal adjudication.\n\nEvery transition persists immutable evidence and an explanation tree in the\nsame transaction (governed contract). Actor provenance is sourced\nfrom the authenticated request context (governed contract).\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_state" ], "properties": { "target_state": { "type": "string", "enum": [ "assigned", "investigating", "findings_submitted", "closed" ], "description": "The target workflow state for this transition." }, "trigger_source": { "type": "string", "enum": [ "rule_threshold", "human_referral" ], "description": "Required on creation; immutable on subsequent advances." }, "assigned_party_id": { "type": "string", "description": "Required on creation; immutable on subsequent advances.", "x-axiom-identifier-classification": "party-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "assigned_role_type": { "type": "string", "description": "Required on creation; immutable on subsequent advances." }, "reason": { "type": "string", "description": "Required on creation." }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "description": "Required and non-empty on creation." }, "fraud_rule_refs": { "type": "array", "items": { "type": "string" }, "description": "Required and non-empty when trigger_source=rule_threshold." }, "disposition": { "type": "string", "enum": [ "substantiated", "unsubstantiated", "settled" ], "description": "Required when target_state=closed; forbidden otherwise." } }, "additionalProperties": false }, "examples": { "create_investigation": { "summary": "Create a new investigation (rule-triggered)", "value": { "target_state": "assigned", "trigger_source": "rule_threshold", "assigned_party_id": "party-siu-001", "assigned_role_type": "siu_investigator", "reason": "Fraud score 0.87 exceeded investigation threshold", "evidence_refs": [ "ev-fraud-score-001" ], "fraud_rule_refs": [ "rule-velocity-001", "rule-amount-002" ] } }, "advance_to_investigating": { "summary": "Advance to investigating", "value": { "target_state": "investigating" } }, "close_investigation": { "summary": "Close with disposition", "value": { "target_state": "closed", "disposition": "substantiated" } } } } } }, "responses": { "200": { "description": "Investigation advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationResponse" }, "example": { "data": { "id": "inv-001", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "state": "investigating" }, "status": "success", "message": "Investigation advanced", "telemetry": { "total_ms": 19, "handler_ms": 15, "trace_id": "vwx234" } } } } }, "201": { "description": "Investigation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationResponse" }, "example": { "data": { "id": "inv-001", "claim_id": "07805e66-69d7-5b42-a978-32729404b560", "state": "assigned", "trigger_source": "rule_threshold", "assigned_party_id": "party-siu-001", "assigned_role_type": "siu_investigator" }, "status": "success", "message": "Investigation created", "telemetry": { "total_ms": 28, "handler_ms": 24, "trace_id": "stu901" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{claimId}/recoveries": { "post": { "operationId": "createRecovery", "x-axiom-wire-success-profile": "json-api", "summary": "Record a recovery event for a claim", "description": "Records a subrogation or salvage recovery event with balanced ledger posting,\nexplanation tree, and evidence \u2014 all atomically in a single transaction.\nRequires X-Tenant-Context and Idempotency-Key headers.\n", "tags": [ "Claim" ], "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecoveryRequest" } } } }, "responses": { "200": { "description": "Idempotent replay \u2014 original response returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEnvelopeResponse" } } } }, "201": { "description": "Recovery recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEnvelopeResponse" } } } }, "404": { "description": "Claim not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict \u2014 same key, different payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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/claims/{claimId}/recoveries/{recoveryId}/corrections": { "post": { "operationId": "createCorrection", "x-axiom-wire-success-profile": "json-api", "summary": "Record a correction for a recovery event", "description": "Creates a correction (full reversal, partial reversal, or write-off) for an\nexisting recovery using compensating ledger entries. Never deletes or updates\noriginal entries (governed contract). Requires X-Tenant-Context and Idempotency-Key headers.\n", "tags": [ "Claim" ], "parameters": [ { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recoveryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCorrectionRequest" } } } }, "responses": { "200": { "description": "Idempotent replay \u2014 original response returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionEnvelopeResponse" } } } }, "201": { "description": "Correction recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionEnvelopeResponse" } } } }, "404": { "description": "Recovery not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict \u2014 same key, different payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "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" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "schemas": { "AssessClaimRequest": { "type": "object", "required": [ "assessed_by", "assessment_notes" ], "properties": { "assessed_by": { "type": "string", "description": "Identifier of the assessor performing the assessment", "example": "assessor-jvd-001" }, "assessment_notes": { "type": "string", "description": "Detailed notes from the assessment", "example": "Site inspection completed. Damage consistent with reported cause. Recommended approval less policy excess of R5,000." }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Approved claim amount. Null if recommending denial.", "nullable": true, "additionalProperties": true }, "item_assessments": { "type": "array", "nullable": true, "description": "Per-item assessment details", "items": { "$ref": "#/components/schemas/ItemAssessment" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata for the assessment", "example": { "inspection_date": "2026-03-05", "photos_attached": 12 } } }, "additionalProperties": false }, "AssessClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimAssessment" }, "assessment": { "type": "array", "description": "Rule evaluation results from tenant-specific adjudication", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": true } ] }, "AuthorisationTransition": { "type": "object", "required": [ "id", "logical_authorisation_id", "entity_type", "entity_id", "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id", "valid_from", "asserted_from" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "logical_authorisation_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "entity_type": { "type": "string", "enum": [ "claim" ] }, "entity_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string" }, "authorisation_kind": { "type": "string" }, "authorising_actor": { "type": "string", "format": "uuid" }, "authorised_scope": { "type": "object", "additionalProperties": true }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "nullable": true }, "governing_version_kind": { "type": "string", "nullable": true }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true }, "compliance_outcome": { "type": "string", "nullable": true }, "compliance_list_version": { "type": "string", "nullable": true }, "compliance_list_authority": { "type": "string", "nullable": true }, "decision_date": { "type": "string", "format": "date-time" }, "explanation_node_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true }, "valid_from": { "type": "string", "format": "date-time" }, "asserted_from": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "Claim": { "type": "object", "required": [ "id", "claim_number", "event_id", "policy_id", "status", "primary_party_id", "event_date", "reported_date", "total_claimed_amount", "description", "priority", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim identifier", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "claim_number": { "type": "string", "description": "Human-readable claim reference number", "readOnly": true, "example": "CLM-2026-00042" }, "event_id": { "type": "string", "format": "uuid", "description": "Reference to the insured event that triggered this claim", "example": "4cbb0168-4d04-535d-969b-927f53d9c96c", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy under which this claim is made", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "status": { "$ref": "#/components/schemas/ClaimStatus" }, "primary_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the primary claimant party", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" }, "event_date": { "type": "string", "format": "date-time", "description": "Date and time when the insured event occurred", "example": "2026-02-15T14:30:00Z" }, "reported_date": { "type": "string", "format": "date-time", "description": "Date and time when the claim was reported", "example": "2026-02-16T09:00:00Z" }, "total_claimed_amount": { "type": "integer", "format": "int64", "readOnly": true, "deprecated": true, "description": "Derived, read-only compatibility field. Equal to SUM(claim_items.claimed_amount). No longer stored as a stored field (governed contract). Amount in the smallest currency unit (e.g. cents). Exact integer representation.\n", "example": 4500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "description": { "type": "string", "description": "Free-text description of the claim circumstances", "example": "Rear-end collision at intersection of Main St and 5th Ave. Third-party vehicle damage and whiplash injury to driver." }, "priority": { "$ref": "#/components/schemas/ClaimPriority" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for tenant-specific claim data", "example": { "loss_location": "London, Greater London", "police_report_number": "MET-2026-LDN-3321", "weather_conditions": "clear" } }, "claim_items": { "type": "array", "nullable": true, "description": "Individual line items making up this claim", "items": { "$ref": "#/components/schemas/ClaimItem" } }, "fraud_score": { "type": "string", "nullable": true, "readOnly": true, "description": "Fraud detection score as exact decimal string in [0, 1]. Null when fraud scoring has not been evaluated for this claim. Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0.25" }, "fraud_status": { "type": "string", "readOnly": true, "enum": [ "not_evaluated", "clear", "suspicious", "confirmed_fraud" ], "description": "Fraud evaluation status. Closed enum \u2014 no other values are valid. Legacy value \"fraudulent\" is a compatibility alias for ingest only; API responses always use \"confirmed_fraud\".\n", "example": "not_evaluated" }, "requires_investigation": { "type": "boolean", "readOnly": true, "description": "Derived from fraud_score >= investigation_threshold. False when fraud scoring has not been evaluated.\n", "example": false }, "is_subrogated": { "type": "boolean", "description": "Whether this claim involves subrogation against a third party.", "example": false }, "subrogation_status": { "type": "string", "readOnly": true, "enum": [ "not_identified", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Subrogation lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_identified" }, "recovery_status": { "type": "string", "readOnly": true, "enum": [ "none", "pending", "partial", "completed", "abandoned" ], "description": "Recovery lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "none" }, "assessments": { "type": "array", "nullable": true, "description": "Assessment records for this claim", "items": { "$ref": "#/components/schemas/ClaimAssessment" } }, "payments": { "type": "array", "nullable": true, "description": "Payment records for this claim", "items": { "$ref": "#/components/schemas/ClaimPayment" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was last updated", "readOnly": true, "example": "2026-02-20T11:30:00Z" } }, "additionalProperties": false }, "ClaimAssessment": { "type": "object", "required": [ "id", "claim_id", "assessment_type", "assessed_by", "assessed_at", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique assessment identifier", "readOnly": true, "example": "cla_01j9zxkp8wqrm2n4v6t5s3d7f6", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the assessed claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "assessment_type": { "type": "string", "description": "Type of assessment performed (e.g. initial, supplementary, independent, medical)", "example": "initial" }, "assessed_by": { "type": "string", "description": "Identifier of the assessor (user ID or external reference)", "example": "assessor-jvd-001" }, "assessed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the assessment was completed", "example": "2026-02-18T16:00:00Z" }, "status": { "type": "string", "enum": [ "approved", "denied", "partial" ], "description": "Assessment outcome status:\n- `approved`: Full claim amount approved\n- `denied`: Claim denied \u2014 no amount approved\n- `partial`: Partial amount approved \u2014 less than total claimed\n", "example": "approved" }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Total amount approved by this assessment. Null if denied.", "nullable": true, "additionalProperties": true }, "denial_reason": { "type": "string", "nullable": true, "description": "Reason for denial or partial denial (null if approved)", "example": null }, "notes": { "type": "string", "nullable": true, "description": "Free-text assessor notes", "example": "All claimed items verified against repair quotations. Approved less R3,000 excess." }, "rule_results": { "type": "array", "nullable": true, "description": "Results from automated rule evaluations during assessment", "items": { "$ref": "#/components/schemas/RuleEvaluationResult" } } }, "additionalProperties": false }, "ClaimItem": { "type": "object", "required": [ "id", "claim_id", "item_type", "description", "claimed_amount", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim item identifier", "readOnly": true, "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the parent claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "item_type": { "type": "string", "description": "Category of the claim item (e.g. vehicle_damage, medical, property, liability)", "example": "vehicle_damage" }, "description": { "type": "string", "description": "Detailed description of the claimed item", "example": "Rear bumper replacement and respray \u2014 2024 Toyota Corolla" }, "claimed_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount claimed for this item (exact integer minor units + lowercase ISO-4217 currency code)." }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount approved by assessor. Null if not yet assessed.", "nullable": true, "additionalProperties": true }, "paid_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount actually paid for this item. Null if not yet paid.", "nullable": true, "additionalProperties": true }, "service_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date when the service or repair was performed", "example": "2026-03-01T08:00:00Z" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for this claim item", "example": { "repair_shop": "Cape Auto Body", "part_numbers": [ "TB-2024-RR-01", "PS-2024-FW-03" ] } }, "status": { "type": "string", "description": "Current status of this claim item", "example": "approved", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "salvage_status": { "type": "string", "readOnly": true, "enum": [ "not_applicable", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Salvage lifecycle status for this claim item. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_applicable" }, "salvage_amount": { "type": "string", "readOnly": true, "description": "Salvage recovery amount as exact decimal string in the smallest currency unit (e.g. cents). Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim item was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" } }, "additionalProperties": false }, "ClaimListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ClaimPayment": { "type": "object", "required": [ "id", "claim_id", "payment_id", "amount_paid", "payment_method", "processed_at", "processed_by", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim payment identifier", "readOnly": true, "example": "cpy_01j9zxkp8wqrm2n4v6t5s3d7f7", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the parent claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "payment_id": { "type": "string", "format": "uuid", "description": "Reference to the payment record in the billing system", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" }, "amount_paid": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount disbursed in this payment (exact integer minor units + lowercase ISO-4217 currency code)." }, "payment_method": { "type": "string", "description": "Method used for payment disbursement", "example": "bank_transfer" }, "processed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was processed", "example": "2026-02-25T10:00:00Z" }, "processed_by": { "type": "string", "description": "Identifier of the user or system that processed the payment", "example": "payments-officer-mk-003" }, "status": { "type": "string", "description": "Current payment status", "example": "completed", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "governed contract authorisation row cited by this payment, when present.", "example": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "x-axiom-identifier-shape": "uuid" }, "authorisation_gate_outcome": { "type": "string", "nullable": true, "description": "Outcome returned by the authorisation payment gate for a cited authorisation.", "enum": [ "clear", "override", "not-applicable" ], "example": "clear" } }, "additionalProperties": false }, "ClaimPriority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "description": "Claim priority level:\n- `low` \u2014 Routine claim, standard handling priority (e.g. minor property damage)\n- `medium` \u2014 Standard claim requiring timely processing (e.g. motor accident)\n- `high` \u2014 Significant claim requiring expedited handling (e.g. business interruption)\n- `urgent` \u2014 Critical claim requiring immediate attention (e.g. hospitalisation, total loss)\n", "example": "medium" }, "ClaimReserve": { "type": "object", "required": [ "id", "claim_id", "policy_id", "reserve_type", "initial_amount", "current_amount", "released_amount", "is_active", "state", "operation", "established_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "claim_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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", "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." }, "reserve_type": { "type": "string" }, "initial_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "current_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "released_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "is_active": { "type": "boolean" }, "state": { "type": "string", "enum": [ "active", "partially_released", "fully_released", "inactive_cancelled" ] }, "reason": { "type": "string" }, "operation": { "type": "string" }, "predecessor_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "successor_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "established_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ClaimStatus": { "type": "string", "enum": [ "submitted", "under_review", "assessed", "partial_approval", "denied", "paid", "closed" ], "description": "Claim entity lifecycle status. The claim lifecycle follows this state machine:\n\n```\nsubmitted -> under_review -> assessed ---------> paid -> closed\n +-> partial_approval -> paid -> closed\n +-> denied ----------------------> closed\n```\n\nTransitions:\n- `submitted` -> `under_review`: Claim enters active review and triage\n- `under_review` -> `assessed`: Full approval \u2014 assessment approves total claimed amount\n- `under_review` -> `partial_approval`: Partial approval \u2014 approved amount is less than claimed\n- `under_review` -> `denied`: Claim denied \u2014 no amount approved\n- `assessed` -> `paid`: Payment disbursed for fully approved claim\n- `partial_approval` -> `paid`: Payment disbursed for partially approved claim\n- `paid` -> `closed`: Claim lifecycle complete after payment\n- `denied` -> `closed`: Claim lifecycle complete after denial\n\nNote: The assessment outcome (approved, denied, partial) is recorded on\n`ClaimAssessment.status`, not on `Claim.status`. The claim entity status\nreflects the overall lifecycle position.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nPer-value descriptions:\n- `submitted`: Claim has been filed and is awaiting initial review\n- `under_review`: Claim is under active assessment by an assessor\n- `assessed`: Assessment complete with full approval; claim is payable\n- `partial_approval`: Assessment complete with partial approval; claim is payable for the approved amount\n- `denied`: Claim has been denied following assessment; no payment will be made\n- `paid`: Payment has been disbursed to the claimant\n- `closed`: Claim lifecycle is complete (paid, denied, or otherwise resolved)\n", "example": "submitted" }, "CorrectionEnvelopeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CorrectionResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CorrectionRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "x-axiom-identifier-shape": "typed-prefix" }, "recovery_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "correction_type": { "type": "string", "enum": [ "full_reversal", "partial_reversal", "write_off" ] }, "amount": { "type": "string", "nullable": true, "description": "String-encoded exact decimal in smallest currency unit (governed contract)", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "effective_at": { "type": "string", "format": "date-time" }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "CorrectionResponse": { "type": "object", "properties": { "correction": { "$ref": "#/components/schemas/CorrectionRecord" }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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 }, "CreateCorrectionRequest": { "type": "object", "required": [ "correction_type", "reason", "evidence_refs", "effective_at" ], "properties": { "correction_type": { "type": "string", "enum": [ "full_reversal", "partial_reversal", "write_off" ], "description": "Type of correction. Closed enum. `full_reversal`: reverses the full original amount. `partial_reversal`: reverses a specified portion. `write_off`: writes off a specified or full amount.\n", "example": "full_reversal" }, "amount": { "type": "string", "nullable": true, "pattern": "^[1-9]\\d*$", "description": "Required for `partial_reversal`, forbidden for `full_reversal`, optional for `write_off`. String-encoded exact decimal in smallest currency unit (e.g. cents). No float (governed contract).\n", "example": "2500000", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reason": { "type": "string", "description": "Reason for the correction", "example": "Recovery recorded in error \u2014 settlement rescinded" }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Non-empty array of evidence references supporting this correction", "example": [ "ev-rescission-notice-001" ] }, "effective_at": { "type": "string", "format": "date-time", "description": "When the correction is effective (RFC 3339)", "example": "2026-03-18T14:00:00Z" } }, "additionalProperties": false }, "CreateRecoveryRequest": { "type": "object", "required": [ "recovery_type", "amount", "currency", "received_at", "reason", "evidence_refs" ], "properties": { "recovery_type": { "type": "string", "enum": [ "subrogation", "salvage" ], "description": "Type of recovery. Closed enum. `subrogation`: claim-level recovery against a liable third party. `salvage`: item-level recovery from damaged goods.\n", "example": "subrogation" }, "claim_item_id": { "type": "string", "format": "typed-prefix-id", "description": "Required for `salvage`, forbidden for `subrogation`. References the specific claim item being salvaged.\n", "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "third_party_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required for `subrogation`, optional for `salvage`. References the liable third-party via party ID.\n", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f9", "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "Recovery amount as string-encoded exact decimal in the smallest currency unit (e.g. cents). String encoding under the contract contract; no float on financial paths (governed contract).\n", "example": "5000000", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "USD" }, "received_at": { "type": "string", "format": "date-time", "description": "When the recovery was received (RFC 3339)", "example": "2026-03-15T10:30:00Z" }, "reason": { "type": "string", "description": "Reason for the recovery", "example": "Third party liability established via settlement agreement" }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Non-empty array of evidence references supporting this recovery", "example": [ "ev-settlement-001", "ev-police-report-042" ] } }, "additionalProperties": false }, "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 }, "InvestigationRecord": { "type": "object", "properties": { "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "claim_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "state": { "type": "string", "enum": [ "assigned", "investigating", "findings_submitted", "closed" ] }, "disposition": { "type": "string", "enum": [ "substantiated", "unsubstantiated", "settled" ], "nullable": true }, "trigger_source": { "type": "string", "enum": [ "rule_threshold", "human_referral" ] }, "assigned_party_id": { "type": "string", "x-axiom-identifier-classification": "party-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "assigned_role_type": { "type": "string" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "fraud_rule_refs": { "type": "array", "items": { "type": "string" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "InvestigationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvestigationRecord" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ItemAssessment": { "type": "object", "properties": { "item_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the claim item being assessed", "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Approved amount for this item." }, "notes": { "type": "string", "description": "Assessment notes specific to this item", "example": "Flooring replacement quote verified with two independent suppliers" } }, "additionalProperties": false }, "Money": { "type": "object", "required": [ "amount_minor", "currency_code" ], "properties": { "amount_minor": { "type": "integer", "format": "int64", "description": "Monetary amount in exact integer minor units (e.g. cents for ZAR/USD/EUR). Never float. The minor-unit exponent derives from currency_code \u2014 never hardcoded.", "example": 123456 }, "currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code (e.g. \"zar\"). Must be non-empty; absent currency is a caller error.", "example": "zar" } }, "additionalProperties": false }, "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 }, "PayClaimRequest": { "type": "object", "required": [ "paid_amount", "payment_method", "processed_by" ], "properties": { "paid_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount to disburse (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "payment_method": { "type": "string", "description": "Payment disbursement method", "example": "bank_transfer" }, "payment_notes": { "type": "string", "nullable": true, "description": "Notes accompanying the payment", "example": "Final settlement \u2014 claim fully resolved" }, "processed_by": { "type": "string", "description": "Identifier of the user or system processing the payment", "example": "payments-officer-mk-003" }, "authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "governed contract authorisation row to cite and gate before payment.", "example": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "x-axiom-identifier-shape": "uuid" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata for the payment", "example": { "bank_reference": "JPMC-ACH-2026030801", "beneficiary_account": "****4521" } } }, "additionalProperties": false }, "PayClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimPayment" }, "ledger_entries": { "type": "array", "description": "Ledger entries created by the claim payment", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecordClaimAuthorisationRequest": { "type": "object", "required": [ "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id" ], "properties": { "logical_authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Logical thread id for grant/amend/revoke chains. Generated when omitted.", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string", "description": "Sector-neutral transition verb.", "example": "authorisation-granted" }, "authorisation_kind": { "type": "string", "description": "Tenant-keyed authorisation kind.", "example": "pre-auth" }, "authorising_actor": { "type": "string", "format": "uuid", "description": "Party-in-role actor that granted the authorisation." }, "authorised_scope": { "type": "object", "additionalProperties": true, "description": "Typed grant envelope such as procedures, codes, or engagement scope." }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "description": "Exact integer minor units for the authorised budget ceiling.", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "nullable": true, "description": "Lowercase ISO-4217 currency code. Present iff budget_minor is present." }, "governing_version_kind": { "type": "string", "nullable": true, "description": "Governing-version discriminator such as catalogue, rule, cover, or engagement-terms." }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Immutable row-id revision of the governing version current at the decision date.", "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true, "description": "Tenant-keyed compliance kind such as accreditation or sanctions-screening." }, "compliance_outcome": { "type": "string", "nullable": true, "enum": [ "clear", "hit", "pending", "unset", "override" ], "description": "Compliance outcome consulted by the payment gate when payment cites this authorisation." }, "compliance_list_version": { "type": "string", "nullable": true, "description": "Tenant-supplied as-was list or standard version." }, "compliance_list_authority": { "type": "string", "nullable": true, "description": "Tenant-keyed list authority such as cms, ofac, ofsi, or eu." }, "decision_date": { "type": "string", "format": "date-time", "description": "Moment the authorisation decision was made." }, "explanation_node_id": { "type": "string", "format": "uuid", "description": "Explanation-node reference for the authorisation decision.", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true, "description": "Required by the persistence rule on revoke or withdrawal transitions." } }, "additionalProperties": false }, "RecordClaimAuthorisationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthorisationTransition" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecoveryEnvelopeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecoveryResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecoveryRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique recovery identifier", "readOnly": true, "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "claim_item_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "recovery_type": { "type": "string", "enum": [ "subrogation", "salvage" ] }, "third_party_party_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "type": "string", "description": "String-encoded exact decimal in smallest currency unit (governed contract)", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "ledger_batch_ref": { "type": "string" }, "explanation_root_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "evidence_entry_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "RecoveryResponse": { "type": "object", "properties": { "recovery": { "$ref": "#/components/schemas/RecoveryRecord" }, "ledger_batch_ref": { "type": "string", "description": "Reference to the balanced ledger batch (transaction ID)", "example": "txn-a1b2c3d4" }, "explanation_root_id": { "type": "string", "description": "Root ID of the explanation tree (governed contract)", "example": "expl-e5f6a7b8", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "evidence_entry_id": { "type": "string", "description": "Evidence entry ID (governed contract)", "example": "evid-c9d0e1f2", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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 }, "ReestablishReserveResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "reserve", "predecessor_id", "successor_id", "operation" ], "properties": { "reserve": { "$ref": "#/components/schemas/ClaimReserve" }, "predecessor_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "successor_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "operation": { "type": "string", "enum": [ "reestablish" ] } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "ReserveListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimReserve" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "ReserveResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClaimReserve" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RuleEvaluationResult": { "type": "object", "required": [ "rule_id", "rule_name", "outcome", "executed_at" ], "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the rule definition", "example": "rule-fraud-score-v2", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "rule_name": { "type": "string", "description": "Human-readable rule name", "example": "Fraud Probability Score" }, "outcome": { "type": "string", "description": "Rule evaluation outcome (e.g. pass, fail, warn, skip)", "example": "pass" }, "value": { "type": "string", "nullable": true, "description": "Rule evaluation output value (type depends on the rule)", "example": "0.12" }, "error": { "type": "string", "nullable": true, "description": "Error message if rule evaluation failed", "example": null }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was evaluated", "example": "2026-02-18T15:58:00Z" } }, "additionalProperties": false }, "SubmitClaimRequest": { "type": "object", "required": [ "event_id", "policy_id", "primary_party_id", "description", "claimed_amount", "event_date" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Reference to the insured event", "example": "4cbb0168-4d04-535d-969b-927f53d9c96c", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy under which the claim is submitted", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "primary_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the primary claimant party", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" }, "description": { "type": "string", "description": "Description of the claim circumstances", "example": "Water damage to ground floor following burst pipe. Affected areas include lounge, kitchen, and hallway flooring." }, "claimed_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Total amount being claimed (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "event_date": { "type": "string", "format": "date", "description": "Date when the insured event occurred (ISO 8601 date)", "example": "2026-03-01" }, "priority": { "$ref": "#/components/schemas/ClaimPriority" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for tenant-specific claim data", "example": { "property_address": "15 Bishopsgate, London, EC2N 3AR", "damage_type": "water" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Operational metadata (integration references, source system info)", "example": { "source_system": "broker-portal", "broker_reference": "BRK-2026-0891" } } }, "additionalProperties": false }, "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 } }, "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" } } ] } } } } } }, "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" } ] } } } } } }, "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": 39, "object_shape": { "closed_object_count": 26, "open_extension_object_count": 30, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 0, "format_constrained_id_count": 34, "classified_id_string_count": 21, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 9, "classified_money_like_count": 0, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 20, "classified_code_string_count": 3, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }