{ "openapi": "3.0.3", "info": { "title": "Axiom API 0.1.1 - Benefits", "description": "Benefit availability and balance operations.", "version": "0.1.1", "contact": { "name": "Axiom Platform Team", "email": "hello@axiom.express" }, "license": { "name": "Proprietary", "url": "https://axiom.express/license" } }, "servers": [ { "url": "https://api.afr-dev.axiom.express", "description": "Africa developer preview" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Benefit", "description": "Benefit balance computation (governed contract). Parameterised queries for\nbenefit utilisation, available balance, and usage decomposition.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Event", "description": "Event and assertion workflows exposed in the developer-preview API.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Policy", "description": "Policy lifecycle \u2014 creation, versioning, endorsements, and status transitions.\nA policy binds a product to parties with specific terms and coverage dates.\nStatus: draft \u2192 active \u2192 suspended \u2192 cancelled \u2192 expired \u2192 lapsed.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Premium", "description": "Premium management \u2014 billing records and premium calculation engine.\nIncludes standalone premium CRUD and product-based calculation with\nadjustments and commission breakdowns.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } } ], "paths": { "/v1/events/{id}/proration-adjustments": { "post": { "description": "Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.", "operationId": "applyProrationAdjustment", "parameters": [ { "description": "Path parameter `id`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentResponse" } } }, "description": "Proration adjustment decision applied." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [ "events:proration-adjust" ] } ], "summary": "Apply Proration Adjustment", "tags": [ "Event", "Premium", "Policy", "Benefit" ], "x-axiom-wire-success-profile": "json-api", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events:proration-adjust" ], "required_permissions": [ "events:proration-adjust" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/balance": { "get": { "operationId": "getBenefitBalance", "x-axiom-wire-success-profile": "json-api", "summary": "Get benefit balance", "description": "Returns the current balance for a specific benefit type on a policy,\nshowing how much of the benefit limit has been consumed.\n\nSupports point-in-time queries via `as_of` and period-scoped queries\nvia `period_start`/`period_end` for benefits with annual or periodic\nlimits (e.g. annual dental limit, per-incident excess cap).\n\nunder the governed contract, benefit balances are computed from the ledger and\nare always consistent with claim payouts and adjustments.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefits for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier (e.g. hospitalisation, dental,\noptical, roadside_assistance, personal_accident).\n", "schema": { "type": "string" }, "example": "hospitalisation" }, { "name": "period_start", "in": "query", "required": false, "description": "Start of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "period_end", "in": "query", "required": false, "description": "End of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time query. Returns the benefit balance as it was\nat this timestamp. Defaults to current time if omitted.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-03-12T00:00:00Z" } ], "responses": { "200": { "description": "Benefit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "balance", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit (decimal as string)", "example": "500000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount consumed (claimed and paid)", "example": "125000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "balance": { "type": "string", "description": "Remaining available balance", "example": "375000.00" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "period_start": { "type": "string", "format": "date", "description": "Start of the benefit period" }, "period_end": { "type": "string", "format": "date", "description": "End of the benefit period" }, "as_of": { "type": "string", "format": "date-time", "description": "Effective timestamp of the balance query" }, "claims_count": { "type": "integer", "description": "Number of claims consuming this benefit in the period" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "hospitalisation", "limit": "500000.00", "consumed": "125000.00", "balance": "375000.00", "currency": "USD", "period_start": "2026-01-01", "period_end": "2026-12-31", "as_of": "2026-03-12T00:00:00Z", "claims_count": 2 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type", "period_start", "period_end" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.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/benefits/available": { "get": { "operationId": "getBenefitAvailable", "x-axiom-wire-success-profile": "json-api", "summary": "Get available benefit amount", "description": "Returns the currently available (claimable) amount for a benefit type\non a policy, accounting for in-flight claims that have been filed\nbut not yet settled.\n\nThis differs from `/balance` in that it includes pending claims\nas reserved amounts, giving a more conservative view of availability\nsuitable for claim intake decisions.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefit availability for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier", "schema": { "type": "string" }, "example": "dental" } ], "responses": { "200": { "description": "Available benefit amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "reserved", "available", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit", "example": "25000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount from settled claims", "example": "8500.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reserved": { "type": "string", "description": "Amount reserved by pending (in-flight) claims", "example": "3200.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "available": { "type": "string", "description": "Amount available for new claims\n(limit - consumed - reserved)\n", "example": "13300.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "pending_claims": { "type": "integer", "description": "Number of in-flight claims reserving benefit", "example": 1 } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "dental", "limit": "25000.00", "consumed": "8500.00", "reserved": "3200.00", "available": "13300.00", "currency": "USD", "pending_claims": 1 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/proration-balances": { "get": { "description": "Read a tenant-owned policy-scoped balance derived from accepted proration decision components for implemented governed contract proration consumers. Slice 1 supports fund and earning balances; treaty-scoped reinsurance balances fail closed until governed treaty authority exists.", "operationId": "getProrationBalance", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Policy ID in pol_ wire form.", "in": "query", "name": "policy_id", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Implemented proration balance consumer. `reinsurance_balance` is an accepted fail-closed value until governed treaty authority exists.\n", "in": "query", "name": "consumer", "required": true, "schema": { "enum": [ "fund_balance", "earning_balance", "reinsurance_balance" ], "type": "string" } }, { "description": "Inclusive balance period start.", "in": "query", "name": "period_start", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive balance period end.", "in": "query", "name": "period_end", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Fund account code, required for fund_balance unless account_code is supplied.", "in": "query", "name": "fund_account_code", "required": false, "schema": { "type": "string" } }, { "description": "Generic account code for fund or earning balance scope.", "in": "query", "name": "account_code", "required": false, "schema": { "type": "string" } }, { "description": "Earning period key, required for earning_balance unless account_code is supplied.", "in": "query", "name": "earning_period_key", "required": false, "schema": { "type": "string" } }, { "description": "Include constituent proration component IDs and operation details.", "in": "query", "name": "decompose", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationBalanceResponse" } } }, "description": "Proration balance result." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [ "policies:read" ] } ], "summary": "Get Proration Balance", "tags": [ "Premium", "Policy", "Benefit" ], "x-axiom-wire-success-profile": "json-api", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "consumer", "period_start", "period_end", "fund_account_code", "account_code", "earning_period_key", "decompose" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "policies:read" ], "required_permissions": [ "policies:read" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "parameters": { "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for end-to-end tracing.\nIf not provided, the server generates one automatically.\nThe response always includes this header for support reference.\n", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.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." }, "example": "req-abc-123-def-456" }, "TenantIdHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "description": "Server-minted tenant-context token (TCT) in request header.\n\n**Required** for all tenant-scoped requests. Obtain it from\n`POST /v1/me/tenant-context` after discovering accessible tenants via\n`GET /v1/me/tenants`. The TCT is a short-lived HMAC-signed token that\ncarries the selected tenant and the authenticated account subject; the\nclient-supplied tenant selectors are not accepted.\n\nThe API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.\n", "schema": { "type": "string" }, "example": "" } }, "schemas": { "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 }, "ProrationAdjustmentComponent": { "type": "object", "description": "Typed effect emitted by a proration decision.", "required": [ "component_type", "consumer", "affected" ], "additionalProperties": false, "properties": { "component_type": { "type": "string", "enum": [ "money", "premium_earning", "cover_limit", "waiting_period", "cover_period", "savings_fund", "backpay_debt", "entitlement_restoration", "reinsurance", "refusal" ] }, "consumer": { "type": "string", "enum": [ "ledger", "entitlement_balance", "temporal_gate", "fund_balance", "earning_balance", "reinsurance_balance", "explanation_only" ] }, "affected": { "type": "object", "additionalProperties": true, "description": "References to the affected primitive instances." }, "amount_minor": { "type": "integer", "format": "int64", "description": "Exact integer minor units for money components." }, "currency": { "type": "string", "description": "Lowercase ISO-4217 currency when amount_minor is present." }, "ratio_bps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Exact basis-point ratio when the component represents a proportion." }, "effective_start": { "type": "string", "format": "date-time" }, "effective_end": { "type": "string", "format": "date-time" }, "reason_code": { "type": "string", "description": "Tenant-owned reason code or fail-closed code." }, "metadata": { "type": "object", "additionalProperties": true } } }, "ProrationAdjustmentDecision": { "type": "object", "description": "Event-effective proration decision resource.", "required": [ "id", "event_id", "status", "event_type", "proration_intent", "components", "ledger_entry_ids", "explanation_tree_id", "evidence_entry_id", "ruleset" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Proration decision UUID.", "example": "f5430790-ad21-526a-945d-f06736f06e55", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "event_id": { "type": "string", "description": "Triggering event identity in wire form.", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "status": { "type": "string", "enum": [ "posted", "evaluated", "refused" ] }, "event_type": { "type": "string", "description": "Event type resolved from the existing triggering event row." }, "proration_intent": { "type": "string", "description": "Tenant ruleset key used for evaluation." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ProrationAdjustmentComponent" } }, "ledger_entry_ids": { "type": "array", "description": "Ledger entry ids created by financial components; empty for zero-money/refused decisions.", "items": { "type": "string" } }, "explanation_tree_id": { "type": "string", "description": "Durable explanation tree identity in wire form.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "evidence_entry_id": { "type": "integer", "format": "int64", "description": "governed contract evidence journal entry id for the persisted decision." }, "ruleset": { "type": "object", "additionalProperties": false, "required": [ "ruleset_type", "ruleset_id", "ruleset_version", "resolved_at" ], "properties": { "ruleset_type": { "type": "string", "example": "proration_adjustments" }, "ruleset_id": { "type": "string", "x-axiom-identifier-classification": "ruleset-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_version": { "type": "string" }, "resolved_at": { "type": "string", "format": "date-time" } } }, "correction_of_decision_id": { "type": "string", "nullable": true, "description": "Original decision id when this decision corrects a prior one.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } }, "ProrationAdjustmentRequest": { "type": "object", "description": "Request to apply a tenant-owned event-effective proration decision. Tenant,\nactor, event type, event effective time, active policy version,\npolicy-product binding, affected party-role authority, affected\npolicy-object authority, product-cover/term authority, ruleset\nbinding/version, ledger categories, and balance-consumer authority are\nderived or validated by the server and must not be supplied as overrides by\nthe caller. Policy and product identities are governed references used for\nserver-side validation and binding resolution; caller-supplied\npolicy-version or product-version overrides are rejected.\n", "required": [ "policy_id", "product_id", "proration_intent", "affected", "effective_times" ], "additionalProperties": false, "properties": { "policy_id": { "type": "string", "description": "Policy identity in wire form.", "example": "pol_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "premium_id": { "type": "string", "description": "Optional premium identity in wire form when the decision affects a known premium.", "example": "prm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "product_id": { "type": "string", "description": "Product identity in wire form. Used by the server to resolve the proration_adjustments ruleset binding.", "example": "prd_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "proration_intent": { "type": "string", "description": "Tenant ruleset key that declares what adjustment intent to evaluate.", "example": "mid_year_join" }, "reason": { "type": "string", "description": "Operator-supplied reason for the adjustment request.", "maxLength": 1024 }, "correction_of_decision_id": { "type": "string", "format": "uuid", "description": "Existing proration decision UUID corrected by this decision.", "x-axiom-identifier-shape": "uuid" }, "affected": { "type": "object", "additionalProperties": false, "required": [ "party_role_id" ], "properties": { "party_role_id": { "type": "string", "description": "Affected party-in-role identity in wire form.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "cover_id": { "type": "string", "description": "Affected cover identity or tenant cover code, if cover-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_term_id": { "type": "string", "description": "Affected cover-level term identity or tenant term code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_item_id": { "type": "string", "description": "Affected cover-item identity or tenant cover-item code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cover_item_term_id": { "type": "string", "description": "Affected cover-item term identity or tenant term code, if term-specific.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_object_id": { "type": "string", "description": "Affected insured object identity in pob_ wire form, if object-specific.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "treaty_id": { "type": "string", "description": "Reserved for future governed treaty authority; current runtime rejects reinsurance proration until that authority substrate exists.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } }, "effective_times": { "type": "object", "additionalProperties": false, "required": [ "premium_period_start", "premium_period_end" ], "properties": { "premium_period_start": { "type": "string", "format": "date-time", "description": "Start of the premium period to evaluate." }, "premium_period_end": { "type": "string", "format": "date-time", "description": "End of the premium period to evaluate." }, "cover_start": { "type": "string", "format": "date-time", "description": "Start of the cover-effective interval when different from premium period." }, "cover_end": { "type": "string", "format": "date-time", "description": "End of the cover-effective interval when different from premium period." }, "entitlement_start": { "type": "string", "format": "date-time", "description": "Start of the entitlement interval when applicable." }, "entitlement_end": { "type": "string", "format": "date-time", "description": "End of the entitlement interval when applicable." } } }, "inputs": { "type": "object", "description": "Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.", "additionalProperties": true } } }, "ProrationAdjustmentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationAdjustmentDecision" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationBalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResult": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount", "item_count" ], "properties": { "currency": { "type": "string", "description": "Lowercase ISO-4217 currency for money balances." }, "amount": { "type": "string", "description": "Decimal string amount produced by the governed contract balance engine.", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "item_count": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "explanation": { "type": "object", "additionalProperties": true } } }, "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" } } ] } } } } } }, "Conflict": { "description": "**409 Conflict**\n\nThe request conflicts with the current state of the resource.\n\nCommon causes:\n- Attempting to create a duplicate resource\n- Optimistic locking failure (stale version)\n- Invalid state transition\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicate": { "summary": "Duplicate resource", "value": { "errors": [ { "status": "409", "code": "DUPLICATE_RESOURCE", "title": "Conflict", "detail": "A policy with this number already exists" } ] } }, "version_conflict": { "summary": "Version conflict", "value": { "errors": [ { "status": "409", "code": "OPTIMISTIC_LOCK_FAILURE", "title": "Conflict", "detail": "Resource was modified by another request. Please refresh and try again.", "meta": { "current_version": 5, "provided_version": 3 } } ] } } } } } }, "Forbidden": { "description": "**403 Forbidden**\n\nThe authenticated user does not have permission to perform this action.\n\nCommon causes:\n- Insufficient role permissions\n- Accessing another tenant's resource\n- Resource-level access control denial\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "errors": [ { "status": "403", "code": "INSUFFICIENT_PERMISSIONS", "title": "Forbidden", "detail": "You do not have permission to perform this action" } ] } }, "tenant_access": { "summary": "Tenant access denied", "value": { "errors": [ { "status": "403", "code": "TENANT_ACCESS_DENIED", "title": "Forbidden", "detail": "You are not authorized to access this tenant's resources" } ] } } } } } }, "InternalError": { "description": "**500 Server Error**\n\nAn unexpected error occurred. The correlation ID can be used\nfor support inquiries.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "500", "code": "SERVER_ERROR", "title": "Server Error", "detail": "An unexpected error occurred. Please try again later.", "meta": { "correlation_id": "req-abc-123-def-456" } } ] } } } }, "NotFound": { "description": "**404 Not Found**\n\nThe requested resource was not found.\n\nNote: For security, we return 404 instead of 403 when the user\nis not authorized to know whether the resource exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "errors": [ { "status": "404", "code": "RESOURCE_NOT_FOUND", "title": "Not Found", "detail": "The requested policy was not found" } ] } }, "endpoint_not_found": { "summary": "Endpoint not found", "value": { "errors": [ { "status": "404", "code": "ENDPOINT_NOT_FOUND", "title": "Not Found", "detail": "The requested endpoint does not exist" } ] } } } } } }, "ServiceUnavailable": { "description": "**503 Service Unavailable**\n\nThe service is temporarily unavailable. Usually due to\nmaintenance or high load.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "503", "code": "SERVICE_UNAVAILABLE", "title": "Service Unavailable", "detail": "The service is temporarily unavailable. Please try again later.", "help_url": "https://developers.afr-dev.axiom.express/api/reference/0.1.1/errors/SERVICE_UNAVAILABLE/", "meta": { "retry_after": 30 } } ] } } } }, "Unauthorized": { "description": "**401 Unauthorized**\n\nAuthentication is required but was not provided or is invalid.\n\nCommon causes:\n- Missing Authorization header\n- Invalid or expired token\n- Malformed credentials\n", "headers": { "WWW-Authenticate": { "description": "Authentication challenge", "schema": { "type": "string", "example": "Bearer realm=\"axiom\", error=\"invalid_token\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_auth": { "summary": "Missing authentication", "value": { "errors": [ { "status": "401", "code": "AUTHENTICATION_REQUIRED", "title": "Unauthorized", "detail": "Authentication is required to access this resource" } ] } }, "expired_token": { "summary": "Expired token", "value": { "errors": [ { "status": "401", "code": "TOKEN_EXPIRED", "title": "Unauthorized", "detail": "The provided authentication token has expired" } ] } } } } } }, "ValidationError": { "description": "**422 Unprocessable Entity**\n\nThe request was well-formed but contained semantic errors.\n\nCommon causes:\n- Field validation failures\n- Business rule violations\n- Invalid state transitions\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "single_field": { "summary": "Single field validation", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'email' must be a valid email address", "source": { "pointer": "/data/attributes/email" } } ] } }, "multiple_fields": { "summary": "Multiple validation errors", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'start_date' is required", "source": { "pointer": "/data/attributes/start_date" } }, { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'premium' must be greater than 0", "source": { "pointer": "/data/attributes/premium" } } ] } }, "business_rule": { "summary": "Business rule violation", "value": { "errors": [ { "status": "422", "code": "BUSINESS_RULE_VIOLATION", "title": "Validation Error", "detail": "Policy end date must be after start date" } ] } } } } } } } }, "x-axiom-schema-contract": { "schema_version": "axiom.public-schema-contract.v1", "posture": "classified-alpha-baseline", "component_schema_count": 11, "object_shape": { "closed_object_count": 11, "open_extension_object_count": 12, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 0, "format_constrained_id_count": 2, "classified_id_string_count": 16, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 0, "classified_money_like_count": 0, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 4, "classified_code_string_count": 1, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }