{ "openapi": "3.0.3", "info": { "title": "Axiom Platform API", "description": "Axiom is programmable insurance infrastructure: one engine for every line of\ninsurance, where the rules are data and every decision can be explained to the\nperson it affects.\n\n## Overview\n\nAxiom provides a complete REST API across the five universal insurance\nprimitives \u2014 parties/roles, covers/products, policies/versions,\npremiums/payments, and events/assertions (under the governed contract). Every feature is\ndesigned API-first under the governed contract.\n\n## Authentication\n\nAll API requests (except health checks) require:\n- **Bearer token** via `Authorization` header (JWT from auth service)\n- **Tenant context** via `X-Tenant-Context` header (server-minted token, required on tenant-scoped endpoints)\n\n## Response Format\n\nMost endpoints currently return a legacy envelope format:\n```json\n{\n \"data\": { ... },\n \"status\": \"success\",\n \"message\": \"optional description\"\n}\n```\n\nError responses:\n```json\n{\n \"error\": \"Human-readable error message\",\n \"status\": \"error\"\n}\n```\n\nNewer endpoints (inbox, ingress, webhooks, vendors) use the JSON:API format\nunder the governed contract. Migration of legacy endpoints to JSON:API is planned.\n\n## Pagination\n\nList endpoints declare their pagination profile per operation. Newer\nconverged list endpoints use cursor-based pagination:\n- `page[size]` \u2014 maximum items per page\n- `page[after]` \u2014 opaque cursor from the previous page\n\nLegacy alpha list endpoints may still use offset-based pagination until\nthey are migrated:\n- `limit` \u2014 maximum items per page\n- `offset` \u2014 number of items to skip\n\nCursor response metadata includes `has_more` and may include `next_cursor`.\nOffset response metadata includes `total`, `limit`, and `offset`.\n\nExample offset metadata:\n```json\n{\n \"data\": [...],\n \"meta\": { \"total\": 150, \"limit\": 20, \"offset\": 0 },\n \"status\": \"success\"\n}\n```\n\n## Correlation Tracing\n\nInclude `X-Correlation-ID` header for end-to-end request tracing.\nIf omitted, the server generates one. The response always includes\n`X-Correlation-ID` for support reference.\n\n## Versioning\n\nAPI families are in the URL path (`/v1/...`). The published contract\nversion is SemVer and is emitted in `info.version`, `X-API-Version`, and\nresponse telemetry under the governed contract.\n\n## Rate Limiting\n\nWhen a tenant-scoped route has an active runtime rate-limit policy,\nresponses include budget headers:\n- `X-RateLimit-Limit` \u2014 active tenant policy limit for the route\n- `X-RateLimit-Remaining` \u2014 remaining requests in the current window\n- `X-RateLimit-Reset` \u2014 window reset time (Unix timestamp)\n\nRejected calls return `429` with `Retry-After`.\n", "version": "0.1.45", "contact": { "name": "Axiom Platform Team", "email": "hello@axiom.express" }, "license": { "name": "Proprietary", "url": "https://axiom.express/license" } }, "servers": [ { "url": "https://api.afr-dev.axiom.express", "description": "Africa developer preview" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Analytics", "description": "Dashboard metrics, claims analysis, revenue trends, and product performance.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Audit", "description": "Audit trail \u2014 recent audit entries for compliance and debugging.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Benefit", "description": "Benefit balance computation (governed contract). Parameterised queries for\nbenefit utilisation, available balance, and usage decomposition.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Catalogue", "description": "Catalogue parent lifecycle, bi-temporal entries, temporal values, relationships, labels, descriptor, source provenance, and bulk-write operations. Governed by governed contract.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Claim", "description": "Claims processing \u2014 submission, assessment, payment, and closure.\nStatus: submitted \u2192 assessing \u2192 assessed \u2192 approved \u2192 paying \u2192 paid \u2192 closed.\nAlso: submitted \u2192 rejected \u2192 closed.\nDeprecated (RFC-8594; Sunset 2026-08-31) in favour of Assertion.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Compliance", "description": "Compliance evaluation engine (governed contract). Evaluates subjects against\nregulatory requirements and produces compliance reports.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Contract", "description": "Generated OpenAPI contract served by the deployed API binary.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Event", "description": "Event and assertion workflows exposed in the developer-preview API.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Evidence", "description": "Evidence records and packs for audit and compliance (governed contract).\nTamper-evident records with content hashing and integrity verification.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Health", "description": "Service health and readiness checks. No authentication required.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Identity", "description": "Authenticated actor, admitted tenant discovery, and tenant-context bootstrap.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ingress", "description": "Async event ingestion (governed contract). Conditionally available event intake with\ntransformation pipeline support. Uses JSON:API response format.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ledger", "description": "Double-entry accounting ledger \u2014 entries, transactions, account balances,\nreversals, integrity verification, and reconciliation. Supports as-of\ntemporal queries with explanation traces.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Party", "description": "Party management \u2014 individuals, organisations, brokers, agents, and providers.\nParties are the actors in the insurance lifecycle (policyholders, claimants,\nbeneficiaries, underwriters).\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Party Group", "description": "Composable party-grouping primitive under the governed contract. Groups can contain\nparties and other groups (polymorphic DAG membership), support static\nand dynamic (CEL-rule-driven) membership, and can hold roles in their\nown right without inheriting to member parties. Distinct from Policy\nGroup (governed contract) which groups policies for cover application.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Payment", "description": "Payment processing \u2014 payment records and payment schedule management.\nSupports bank transfer, credit card, debit order, and other methods.\nStatus: pending \u2192 processing \u2192 completed \u2192 failed \u2192 cancelled.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Policy", "description": "Policy lifecycle \u2014 creation, versioning, endorsements, and status transitions.\nA policy binds a product to parties with specific terms and coverage dates.\nStatus: draft \u2192 active \u2192 suspended \u2192 cancelled \u2192 expired \u2192 lapsed.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Premium", "description": "Premium management \u2014 billing records and premium calculation engine.\nIncludes standalone premium CRUD and product-based calculation with\nadjustments and commission breakdowns.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Product", "description": "Insurance product catalogue \u2014 product definitions, covers, cover provisions,\nterms, pricing rules, and commissions. Products are templates from which\npolicies are created. Supports motor, property, health, life, liability, and more.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Report", "description": "Report generation and export (PDF, CSV).\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Ruleset", "description": "Business rules engine \u2014 rulesets, rules, testing, and deployment.\nRules are data.: explicit, versioned, deterministic, auditable.\nSupports CEL expressions, conditions, and actions.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Vendor", "description": "Vendor registry and risk management (governed contract). Tracks vendors,\nintegrations, data access, and subprocessor approvals.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "name": "Webhook", "description": "Outbound webhook dispatch (governed contract). Register webhook endpoints\nand track delivery status. Uses JSON:API response format.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } } ], "paths": { "/openapi": { "get": { "operationId": "getOpenAPIContract", "summary": "Get the deployed OpenAPI contract", "description": "Returns the generated OpenAPI 3 contract embedded in the running API binary.\nThe SHA-256 digest of this exact document is exposed on `/v1/health` under\n`contract.sha256` for deployed-contract verification.\n", "tags": [ "Contract" ], "security": [], "responses": { "200": { "description": "Generated OpenAPI 3 contract for the deployed API binary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true, "properties": { "openapi": { "type": "string", "pattern": "^3\\.", "example": "3.0.3" }, "info": { "type": "object", "additionalProperties": true }, "paths": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Contract endpoint not found (misconfigured route).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/openapi": { "get": { "operationId": "getVersionedOpenAPIContract", "summary": "Get the deployed OpenAPI contract", "description": "Versioned alias for `/openapi`. Returns the generated OpenAPI 3 contract\nembedded in the running API binary.\n", "tags": [ "Contract" ], "security": [], "responses": { "200": { "description": "Generated OpenAPI 3 contract for the deployed API binary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true, "properties": { "openapi": { "type": "string", "pattern": "^3\\.", "example": "3.0.3" }, "info": { "type": "object", "additionalProperties": true }, "paths": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Contract endpoint not found (misconfigured route).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Check API health", "description": "Returns the current developer-facing API health status. Use this endpoint for connectivity checks and include X-Correlation-ID when escalating an unexpected result.", "security": [], "responses": { "200": { "description": "API is reachable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "example": "healthy", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } } }, "example": { "status": "healthy", "timestamp": "2026-08-09T00:00:00Z", "version": "0.1.45" } } } }, "503": { "description": "API is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "example": "unavailable", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "timestamp": { "type": "string", "format": "date-time" } } }, "example": { "status": "unavailable", "timestamp": "2026-08-09T00:00:00Z" } } } } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "endpoint-specific", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "not-required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "not-applicable", "tenant_context": "not-required", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "no-authentication-required" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/uploads": { "post": { "operationId": "initiateObjectUpload", "summary": "Initiate a presigned object upload", "description": "Returns a short-lived presigned PUT URL the caller uses to upload a binary\npayload directly to object storage (S3-compatible), bypassing the API for\nthe bytes themselves. The returned `upload_id` is then referenced in a\ndownstream ingest call (e.g. POST /v1/catalogues/{catalogue-ref}/bulk-write).\n\nThe response is a bare `{data: ...}` envelope (no `status` field).\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "responses": { "200": { "description": "Presigned upload initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/objectUploadInitiateResponse" }, "example": { "data": { "upload_id": "310cf32d-9203-5f14-9574-38c755ef42fa", "put_url": "https://api.afr-dev.axiom.express/v1/objects/310cf32d-9203-5f14-9574-38c755ef42fa?X-Amz-Signature=...", "object_uri": "managed-object://redacted", "expires_at": "2026-06-02T13:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "presigned-upload-initiation", "api_byte_transport": "metadata-only", "numeric_byte_limit": "not-published", "commitment_status": "unavailable", "enforcement_owner": "object-store-presigned-put", "replacement_decision": "Publish an object-size commitment only when the presigned PUT flow exposes a runtime-enforced content-length-range condition or equivalent object-store policy proof." }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJobStatus", "summary": "Get async job status", "description": "Returns the current state of an async job. Terminal states\n(`succeeded`, `failed`, `dead_letter`) are cacheable; non-terminal states\n(`queued`, `running`) are returned with no-store.\n\nThe response is a bare `{data: ...}` envelope (no `status` field).\n", "tags": [ "Contract" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "UUID of the async job to poll.", "example": "310cf32d-9203-5f14-9574-38c755ef42fa" } ], "responses": { "200": { "description": "Job status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/jobStatusResponse" }, "example": { "data": { "id": "310cf32d-9203-5f14-9574-38c755ef42fa", "kind": "catalogue.ingest", "state": "running", "submitted_at": "2026-06-02T12:00:00Z", "attempt": 1, "max_attempts": 3, "progress": { "completed_units": 1200, "total_units": 5000, "message": "ingesting entries" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/replacements": { "post": { "operationId": "initiateReplacement", "summary": "Initiate a policy replacement", "description": "Starts a replacement workflow that supersedes one or more existing policies\nwith a replacement policy. Returns the initial workflow state including the\nallowed transitions from the starting step.\n", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementInitiateRequest" }, "example": { "policy_id": "pol_01j1234567890abcdefghijk", "existing_policy_ids": [ "pol_01j9876543210abcdefghijk" ], "jurisdiction_code": "za", "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Customer requested upgrade to comprehensive cover", "occurred_at": "2026-06-02T12:00:00Z" } } } }, "responses": { "201": { "description": "Replacement workflow initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}": { "get": { "operationId": "getReplacement", "summary": "Get a replacement workflow", "description": "Fetch the current state of a replacement workflow by id.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "responses": { "200": { "description": "Replacement workflow state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/advance": { "post": { "operationId": "advanceReplacement", "summary": "Advance a replacement workflow", "description": "Advances the workflow to the next step, supplying the evidence payload\nrequired by the current step. Optimistic-concurrency via `version`.\n", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementAdvanceRequest" }, "example": { "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Replacement disclosure acknowledged", "occurred_at": "2026-06-02T12:05:00Z", "evidence_payload": { "disclosure_acknowledged": true }, "version": 1 } } } }, "responses": { "200": { "description": "Replacement advanced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/cancel": { "post": { "operationId": "cancelReplacement", "summary": "Cancel a replacement workflow", "description": "Cancels an in-flight replacement workflow. Optimistic-concurrency via `version`.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementCancelRequest" }, "example": { "actor": { "actor_type": "human", "actor_id": "usr_01j1234567890abcdefghijk", "actor_original_id": "usr_01j1234567890abcdefghijk" }, "reason": "Customer withdrew request", "occurred_at": "2026-06-02T12:10:00Z", "version": 1 } } } }, "responses": { "200": { "description": "Replacement cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementSingleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/evidence": { "get": { "operationId": "getReplacementEvidence", "summary": "Get replacement evidence", "description": "Returns the evidence collected per step for a replacement workflow.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "responses": { "200": { "description": "Replacement evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementEvidenceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/archive/objects": { "post": { "operationId": "ingestArchiveObject", "summary": "Upload an object to the archive", "description": "Multipart upload of a single binary payload into the Axiom archive.\nThe `file` part is required; `original_filename`, `mime_type`, and `source`\nare optional. When omitted, the API derives them from the file header,\nContent-Type, and literal source `\"api\"`.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The binary payload to archive." }, "original_filename": { "type": "string", "description": "Original filename; falls back to the upload part's filename." }, "mime_type": { "type": "string", "description": "MIME type; falls back to the part Content-Type or application/octet-stream." }, "source": { "type": "string", "description": "Provenance tag (default \"api\")." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Object archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveIngestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events": { "get": { "description": "Contract authority for GET /v1/events (listEvents) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "listEvents", "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "events:read" ] } ], "summary": "List Events", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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.45 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": "standard", "scopes": [ "events:read" ], "required_permissions": [ "events: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/events/{id}": { "get": { "description": "Contract authority for GET /v1/events/{id} (getEvent) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getEvent", "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.45 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": "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "events:read" ] } ], "summary": "Get Event", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:read" ], "required_permissions": [ "events: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/events/{event_id}/documents": { "post": { "description": "Contract authority for POST /v1/events/{event_id}/documents (uploadEventDocuments) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "uploadEventDocuments", "parameters": [ { "description": "Path parameter `event_id`.", "in": "path", "name": "event_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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "events:document" ] } ], "summary": "Upload Event Documents", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:document" ], "required_permissions": [ "events:document" ], "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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events/report": { "post": { "description": "Record a tenant-reported event with supporting documents. An event is the Axiom assertion primitive \u2014 it captures what happened, who reported it, and what documentary evidence supports it. The operation is idempotency-optional; events are append-only and duplicate-safe through the assertion model. Ledger effects, if any, are produced by downstream rules evaluation against the stored assertion.", "operationId": "reportEventWithDocuments", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventReportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReportResponse" } } }, "description": "Event reported with documents." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [ "events:report" ] } ], "summary": "Report Event", "tags": [ "Event", "Evidence" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events:report" ], "required_permissions": [ "events:report" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events/{id}/proration-adjustments": { "post": { "description": "Evaluate and persist a tenant-owned event-effective proration decision for an existing event/assertion. The operation creates an immutable proration decision with typed components. Financial components may post through the ledger; non-financial components are durable decision inputs consumed by dynamic balance and temporal engines.", "operationId": "applyProrationAdjustment", "parameters": [ { "description": "Path parameter `id`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationAdjustmentResponse" } } }, "description": "Proration adjustment decision applied." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [ "events:proration-adjust" ] } ], "summary": "Apply Proration Adjustment", "tags": [ "Event", "Premium", "Policy", "Benefit" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events:proration-adjust" ], "required_permissions": [ "events:proration-adjust" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/role-types": { "get": { "operationId": "listRoleTypes", "summary": "List available party role types", "description": "Returns the catalogue of party role types available to the tenant. This\nis the permissible role_type vocabulary and metadata, not the set of role\ntypes currently in use. Use `GET /v1/parties/role-types/usage` for active\nassignment counts.\n\nRuntime source: the tenant `catalogue.role_types` table. Bootstrap\nregistry metadata may enrich known seed codes, but the tenant catalogue is\nthe authority for which role_type values are available.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "responses": { "200": { "description": "Available party role types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTypeListResponse" }, "example": { "data": [ { "code": "policyholder", "display_name": "Policyholder", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true }, { "code": "beneficiary", "display_name": "Beneficiary", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true } ], "meta": { "total": 18, "limit": 18, "offset": 0 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/role-types/usage": { "get": { "operationId": "listRoleTypeUsage", "summary": "Role-type usage counts", "description": "Returns each role type that has at least one active (non-revoked)\nassignment for the tenant, with the count of holders. Role types in the\nregistry with zero holders are not returned \u2014 pair with\n`GET /v1/parties/role-types` to render \"available but unused\" rows.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "responses": { "200": { "description": "Role-type usage counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTypeUsageListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties": { "post": { "description": "Register a party identity record that may later carry roles. A party is the foundational Axiom primitive anchoring all relationships \u2014 to covers, policies, premiums, and events. This contract creates the identity record; role assignment is a separate operation.", "operationId": "createParty", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } }, "description": "Party created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request, including invalid lifecycle transition shape such as status=merged without merged_into_party_id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Server Error" } }, "security": [ { "BearerAuth": [ "parties:register" ] } ], "summary": "Register Party", "tags": [ "Party" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "parties:register" ], "required_permissions": [ "parties:register" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listParties", "summary": "List parties", "description": "Retrieve a paginated list of parties for the tenant.\nResults are sorted by created_at descending. Sort order is not configurable.\n\nSupports cursor-based pagination via page[size] and page[after] query parameters.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of parties to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page." }, { "name": "source_system", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "description": "Exact external identifier source-system filter. Must be supplied together with external_id; unknown values return 400 INVALID_REQUEST with accepted values in the error detail." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Exact external identifier filter. Must be supplied together with source_system so bare external_id cannot create ambiguous identity resolution." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3 }, "description": "Free-text search term for Party lookup. The runtime rejects search terms shorter than three characters." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tenant `catalogue.role_types` code filter for parties currently holding the role." } ], "responses": { "200": { "description": "Parties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "source_system", "external_id", "q", "role" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}": { "get": { "operationId": "getParty", "summary": "Get a party by ID", "description": "Retrieve a single party by its unique identifier, including any assigned roles.\nWhen as_of or recorded_at is supplied, the response replays the party from\nthe immutable party history substrate using effective time and recorded time\nas-was semantics.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "RFC3339 effective-time timestamp for party history replay. Defaults to current effective time." }, { "name": "recorded_at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "RFC3339 recorded-time timestamp for as-was party history replay. Defaults to the latest recorded version." } ], "responses": { "200": { "description": "Party retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "recorded_at" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateParty", "summary": "Update a party", "description": "Update an existing party's attributes and/or status.\nAttribute updates are merged with existing attributes (partial update semantics).\n\nSide effects: updates the party record; emits an audit entry recording the change.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartyRequest" } } } }, "responses": { "200": { "description": "Party updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/roles": { "get": { "operationId": "getPartyRoles", "summary": "Get roles assigned to a party", "description": "Retrieve all role assignments for a party across policies, claims, and other entities.\nEach role includes the context (entity type and ID) it is scoped to.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Party roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "addPartyRole", "summary": "Assign a role to a party", "description": "Assign a new role to a party, scoped to a specific entity (e.g. a policy,\nclaim, product, organization, policy item, or PartyGroup). For sponsor\nrole assignments on a group context, the sponsor remains the Party role\nassignee and the PartyGroup is identified by entity_type=group/entity_id.\nOnly one active sponsor is allowed per tenant/group context; duplicate\nactive sponsor attempts return SPONSOR_CARDINALITY_VIOLATED (HTTP 409).\n\nA party can hold multiple roles simultaneously, and the same party can hold\ndifferent roles on different entities.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role_type", "entity_type", "entity_id", "assigned_by" ], "properties": { "role_type": { "type": "string", "description": "Tenant `catalogue.role_types` code to assign. The server validates the code against the tenant catalogue, not a closed OpenAPI enum." }, "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item", "group" ], "description": "The type of entity this role is scoped to" }, "entity_id": { "type": "string", "format": "typed-prefix-id", "description": "The identifier of the entity this role is scoped to", "x-axiom-identifier-shape": "typed-prefix" }, "assigned_by": { "type": "string", "description": "Identifier of the user or service assigning this role" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional attributes for the role assignment" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Role assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/contacts": { "get": { "operationId": "listPartyContacts", "summary": "List contacts for a party", "description": "Retrieve all contact records associated with a party. A party may have multiple\ncontacts (e.g. personal email, work email, mobile, landline).\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Contacts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyContact", "summary": "Add a contact to a party", "description": "Create a new contact record for a party. Each contact includes an email address,\nphone number, and/or preferred contact method. Parties in opted_out status reject\nnew contact capture with a 409 while historical contact reads remain available.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInfo" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/contacts/{contactId}": { "put": { "operationId": "updatePartyContact", "summary": "Update a party contact", "description": "Update an existing contact record for a party.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique contact identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInfo" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyContactResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deletePartyContact", "summary": "Delete a party contact", "description": "Remove a contact record from a party.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique contact identifier" } ], "responses": { "204": { "description": "Contact deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/identities": { "get": { "operationId": "listPartyIdentities", "summary": "List identity documents for a party", "description": "Retrieve all identity documents associated with a party (e.g. passport, national ID,\ntax number, company registration). Each identity has a verification status.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "responses": { "200": { "description": "Identities retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyIdentity", "summary": "Add an identity document to a party", "description": "Register a new identity document for a party. The identity is created in\n\"unverified\" status and must be verified separately via the verify endpoint.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "identity_type", "identity_value" ], "properties": { "identity_type": { "type": "string", "description": "Type of identity document" }, "identity_value": { "type": "string", "description": "The identity document number or value" }, "issuing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code of issuing authority" }, "expiry_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiry date of the identity document" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Identity document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/identities/{identityId}/verify": { "post": { "operationId": "verifyPartyIdentity", "summary": "Verify a party identity document", "description": "Mark an identity document as verified. This records the verification timestamp\nand transitions the identity status from \"unverified\" to \"verified\".\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "identityId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique identity document identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_method": { "type": "string", "description": "Method used for verification (e.g. manual, electronic, biometric)" }, "verified_by": { "type": "string", "description": "Identifier of the user or service performing verification" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes about the verification" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Identity verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyIdentityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/relationships": { "get": { "operationId": "getPartyRelationships", "summary": "List relationships for a party", "description": "Retrieve relationships for a party. The view parameter selects the response shape:\n\n- list (default): returns all active relationships as a flat array of relationship objects.\n- distribution_chain: traverses the distribution chain from this party, returning\n participants and an explanation tree (governed contract).\n\nAn unrecognised view value returns 400 INVALID_REQUEST under the governed contract.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "list", "distribution_chain" ], "default": "list" }, "description": "Response view type. Unknown values return 400 INVALID_REQUEST under the governed contract." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time filter for relationships (ISO 8601). Defaults to current time." }, { "name": "relationship_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tenant `catalogue.relationship_types` code filter." }, { "name": "max_depth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 16 }, "description": "Maximum traversal depth for view=distribution_chain (1-16). Ignored for view=list." } ], "responses": { "200": { "description": "Relationships retrieved successfully. Shape depends on the view parameter.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PartyRelationshipListResponse" }, { "$ref": "#/components/schemas/PartyDistributionChainResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "relationship_type", "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyRelationship", "summary": "Create a relationship between two parties", "description": "Creates a directed relationship from the identified party (from_party_id) to another\nparty (to_party_id). On success, returns 201 Created with the new relationship resource.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to_party_id", "relationship_type" ], "properties": { "to_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Target party for the relationship", "x-axiom-identifier-shape": "typed-prefix" }, "relationship_type": { "type": "string", "description": "Tenant `catalogue.relationship_types` code. The server validates the code against the tenant catalogue, not a closed OpenAPI enum." }, "effective_from": { "type": "string", "format": "date-time", "nullable": true, "description": "Relationship valid-from timestamp (ISO 8601). Defaults to now." }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Relationship expiry timestamp. Null means open-ended." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional key-value metadata for the relationship" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Relationship created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRelationshipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/relationships/{relId}": { "delete": { "operationId": "deletePartyRelationship", "summary": "Delete (deactivate) a party relationship", "description": "Temporally deactivates a relationship by setting its effective_to to now.\nIdempotent \u2014 deactivating an already inactive relationship returns 204.\n\nBody `{\"reason\": \"...\"}` is required (non-blank after trim) per .\nBlank reason returns 400 PARTY_DEACTIVATION_REASON_REQUIRED.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "relId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Unique relationship identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Non-blank rationale for the deactivation. Recorded on the audit record under the governed contract." } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Relationship deleted (deactivated) successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/party-groups": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "pty_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listGroupsForParty", "summary": "List party groups containing this party", "description": "Inverse projection \u2014 returns the groups the given party is a member\nof as of `as_of`. Distinct from `/v1/parties/:id/groups` which\nreturns Policy Group (governed contract) memberships.\n", "tags": [ "Party", "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Groups the party belongs to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/groups": { "get": { "operationId": "listPartyPolicyGroups", "summary": "List the policy-driven groups a party belongs to", "description": "Returns the **transitive** policy-group membership view for a party: the\ngroups the party belongs to by virtue of a policy binding, each annotated\nwith the `via_policy_id` that confers the membership. This is distinct\nfrom `/v1/parties/{id}/party-groups` (first-class, directly-assigned\nparty-group memberships) \u2014 here membership is derived from policy\nparticipation, not a direct grouping assignment.\n\nPoint-in-time: pass `as_of` (RFC3339) to resolve membership as it stood at\nthat instant; defaults to now.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Resolve membership as-of this instant (RFC3339). Defaults to now." } ], "responses": { "200": { "description": "Policy-driven group memberships for the party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyPolicyGroupListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/payments": { "get": { "operationId": "getPartyPayments", "summary": "List payments for a party", "description": "Retrieves a paginated list of payments associated with a specific party.\nReturns only payments explicitly linked to the party via `party_id`.\nPayments without party linkage (null `party_id`) are excluded.\n\nResults are sorted by created_at descending with id as a stable\ntie-breaker. Use `page[size]` and `page[after]` for pagination. Legacy\n`limit` and `offset` query parameters are rejected.\n", "tags": [ "Party", "Payment" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of payments to return" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Party payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyPaymentListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/audit": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyAudit", "summary": "Chronological audit feed for a party", "description": "Returns the per-party audit feed in chronological order\n(`performed_at DESC`). Each event carries governed contract actor attribution\n(`actor_id` / `actor_type` / `actor_original_id`) regardless of\nwriter path. The reader merges persistence-managed records and application writes\nso the consumer sees a single shape.\n\nExplanation enrichment fields (`decision_id`, `rule_versions`,\n`inputs`) are populated for rules-evaluation records only and\nempty otherwise (preview placeholder).\n\nUse `page[size]` and `page[after]` for cursor pagination. Legacy\n`limit` and `offset` query parameters are rejected by the runtime.\n", "tags": [ "Party" ], "parameters": [ { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of audit entries to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Audit feed for this party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyAuditListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/audit": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupAudit", "summary": "Chronological audit feed for a party group", "description": "Returns the per-group audit feed in chronological order\n(`performed_at DESC`). party_groups + party_group_memberships have\nno persistence-managed records, so every row is generated by the\napplication's `NewAuditRecord` path with a `party.group_*`\noperation code.\n\nResponse shape mirrors `/v1/parties/{id}/audit` \u2014 see that endpoint\nfor the full `AuditEntry` field list.\n\nUse `page[size]` and `page[after]` for cursor pagination. Legacy\n`limit` and `offset` query parameters are rejected by the runtime.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of audit entries to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." } ], "responses": { "200": { "description": "Audit feed for this party group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupAuditListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues": { "get": { "operationId": "listCatalogues", "summary": "List catalogues", "description": "Returns catalogue parents visible to the caller's tenant. Tenant-scoped\ncatalogues from other tenants are filtered out (not 404'd individually).\nTenant isolation is enforced at the persistence layer by tenant-isolated.\n\nOptional `slug` filter for exact slug match; `include_discarded` exposes\nsoft-discarded parents for audit / recovery purposes (defaults false).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "slug", "in": "query", "required": false, "description": "Exact catalogue slug filter (e.g. `icd-10-za`).", "schema": { "type": "string" } }, { "name": "include_discarded", "in": "query", "required": false, "description": "When true, includes soft-discarded catalogue parents in the result.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of catalogue parents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalogueListResponse" }, "example": { "data": [ { "id": "cc347178-b31f-571d-8ed1-b2513427d36f", "slug": "icd-10-za", "name": "ICD-10-ZA", "source": "WHO/DoH-ZA", "refresh_frequency": "annual", "substrate": "bi-temporal", "has_descriptor": false, "created_at": "2026-01-15T08:00:00Z", "updated_at": "2026-01-15T08:00:00Z" } ], "meta": { "limit": 0, "offset": 0, "count": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "slug", "include_discarded" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}": { "get": { "operationId": "getCatalogue", "summary": "Get catalogue", "description": "Fetch a single catalogue parent by its slug identifier. Returns\ndiscarded parents too (audit / as-was reconstruction); the\n`discarded_at`, `discarded_by`, and `discard_reason` fields are\npopulated when set.\n\nTenant isolation enforced at persistence layer by tenant-isolated. Cross-tenant\nslugs yield 404, not 403.\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRefPath" } ], "responses": { "200": { "description": "Catalogue parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalogueSingleResponse" }, "example": { "data": { "id": "cc347178-b31f-571d-8ed1-b2513427d36f", "slug": "icd-10-za", "name": "ICD-10-ZA", "source": "WHO/DoH-ZA", "refresh_frequency": "annual", "substrate": "bi-temporal", "has_descriptor": false, "created_at": "2026-01-15T08:00:00Z", "updated_at": "2026-01-15T08:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}/entries": { "get": { "operationId": "listCatalogueEntries", "summary": "List bi-temporal entries", "description": "Returns bi-temporal catalogue entries for the given catalogue parent,\nfiltered by the two-axis as-was window (`as_of` / `recorded_at`).\nTenant isolation enforced at the persistence layer by tenant-isolated.\n\nOptional filters:\n- `logical_entry_id` \u2014 return all versions of a single logical entry UUID.\n- `code` \u2014 exact code match.\n- `q` \u2014 keyword search on description.\n- `order_by=attr.` \u2014 sort by a descriptor-declared attribute field\n (contract rule; fails 400 DESCRIPTOR_FIELD_NOT_SORTABLE when the field is not\n declared in the catalogue descriptor's `roles.sort.fields`).\n- `dir=asc|desc` \u2014 sort direction (default `asc`).\n- `attr.=` \u2014 JSONB-containment filter on any attribute field\n (contract rule; when the catalogue descriptor declares `roles.search.fields`,\n only declared fields are accepted; undeclared \u2192 400 DESCRIPTOR_FIELD_NOT_SEARCHABLE).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRefPath" }, { "name": "as_of", "in": "query", "required": false, "description": "Real-world validity axis instant (RFC 3339). When provided, only\nentries whose `valid_from <= as_of < valid_to` (or `valid_to IS NULL`)\nare returned.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "recorded_at", "in": "query", "required": false, "description": "Physical-anchor axis instant (RFC 3339). When provided, only\nentries whose `recorded_from <= recorded_at` are returned, enabling\nas-was reconstruction at a prior recording moment.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "logical_entry_id", "in": "query", "required": false, "description": "UUID of the logical entry; returns all bi-temporal versions for that entry.", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "code", "in": "query", "required": false, "description": "Exact code match filter.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Keyword search on the entry description field.", "schema": { "type": "string" } }, { "name": "order_by", "in": "query", "required": false, "description": "Attribute sort field in the form `attr.`. Only fields declared in\nthe catalogue descriptor `roles.sort.fields` are accepted (contract rule allow-list).\n", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction. One of `asc` or `desc`. Defaults to `asc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Bi-temporal entries list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/biTemporalEntryListResponse" }, "example": { "entries": [ { "id": "cae_01j1234567890abcdefghijk", "logical_entry_id": "310cf32d-9203-5f14-9574-38c755ef42fa", "catalogue_id": "cat_01j1234567890abcdefghijk", "code": "J18.9", "description": "Pneumonia, unspecified organism", "status": "active", "valid_from": "2026-01-01T00:00:00Z", "recorded_from": "2026-01-15T08:00:00Z", "created_at": "2026-01-15T08:00:00Z" } ], "count": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "recorded_at", "logical_entry_id", "code", "q" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/catalogues/{catalogue-ref}/relationships/batch": { "post": { "operationId": "createCatalogueRelationshipBatch", "summary": "Atomically create N relationships in one transaction", "description": "Atomic batch create under the governed contract. Either every row in the\n`relationships` array is persisted, or none are. The path\n:catalogue-ref scopes the batch \u2014 every row's source_catalogue MUST\nequal the path. Unlike the single-create endpoint, source fields are\nNOT defaulted from the path; each row must specify them explicitly.\nMaximum batch size is 10000 (BATCH_SIZE_EXCEEDED 400 above that).\n", "tags": [ "Catalogue" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/CatalogueRelationshipRefPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "relationships" ], "properties": { "relationships": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/CatalogueRelationshipBody" } } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "All relationships created atomically.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "relationships", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogueRelationship" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups": { "get": { "operationId": "listPartyGroups", "summary": "List party groups", "description": "Returns party groups for the tenant with cursor pagination. Results are\nordered by created_at descending with id as a stable tiebreaker. Supports\na free-text search via `q` (3-character minimum under the governed contract).\n", "tags": [ "Party Group" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of party groups to return in this cursor page." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page." }, { "name": "q", "in": "query", "description": "Search across display_name, id, external_id (min 3 chars, governed contract)", "schema": { "type": "string", "minLength": 3 } } ], "responses": { "200": { "description": "Party group list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "q" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPartyGroup", "summary": "Create a party group", "description": "Creates a static or dynamic party group. For dynamic groups,\n`membership_rule_id` is required and must reference a rule of type\n`party_grouping` in the shared rules catalog (fail-loud; 400 on\ninvalid reference). Idempotent via standard Idempotency-Key header.\n", "tags": [ "Party Group" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartyGroupRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "getPartyGroup", "summary": "Get a party group with its active members", "description": "Returns the group and its active memberships as of `as_of` (defaults\nto now). Members include both party-type and group-type (developer preview\npolymorphic DAG) \u2014 callers must discriminate on `member_type`.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Group + members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updatePartyGroup", "summary": "Update display_name / description / status", "description": "Partial update \u2014 only supplied fields are changed. Soft-delete is\nachieved via setting status to `inactive` here OR calling DELETE.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartyGroupRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deletePartyGroup", "summary": "Soft delete (status \u2192 inactive)", "description": "Soft-delete \u2014 flips status to `inactive`. The group row and its\nmemberships are preserved for audit under the governed contract. There is no hard\ndelete.\n", "tags": [ "Party Group" ], "responses": { "204": { "description": "Deleted (soft)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/members": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "post": { "operationId": "addPartyGroupMember", "summary": "Add a party or group as a member", "description": "Body must supply exactly one of `party_id` or `group_id`. Neither or\nboth \u2192 400. Cycle detection happens at read time (bounded traversal, governed contract) \u2014 writes do not block cyclic membership.\nIdempotent on (group, member_type, member_id) when a membership is\nalready open.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPartyGroupMemberRequest" } } } }, "responses": { "201": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupMembershipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/members/{partyId}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "partyId", "in": "path", "required": true, "description": "Member id. The path parameter is named `partyId` for legacy reasons;\nthe endpoint accepts both party-member-ids and group-member-ids\n(developer preview \u2014 any member_id regardless of type).\n", "schema": { "type": "string", "format": "typed-prefix-id", "example": "pty_01arz3ndektsv4rrffq69g5fav" } } ], "delete": { "operationId": "removePartyGroupMember", "summary": "Close a member's open window (sets valid_to = now)", "description": "Idempotent \u2014 if no open membership exists, returns 204 without error.\nDoes not hard-delete the membership row; the closed window is\npreserved for audit (governed contract).\n", "tags": [ "Party Group" ], "responses": { "204": { "description": "Membership closed (or no-op if already closed)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/flat-members": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupFlatMembers", "summary": "List all party members reachable via recursive expansion", "description": "Recursively walks the membership DAG and returns every party that is\nreachable \u2014 de-duplicated by party_id. Uses bounded traversal with a\ncycle guard (governed contract): diamonds are de-duped, cycles are\nshort-circuited.\n", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "description": "BFS depth cap [1, 16]. Server returns 400 for out-of-range. 0 or omitted \u2192 default (4).", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "De-duplicated flat member list with paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupFlatMemberListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/ancestors": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupAncestors", "summary": "List groups that transitively contain this group", "description": "BFS upward through the membership DAG up to `max_depth`.", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "Ancestor groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/descendants": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupDescendants", "summary": "List groups transitively contained by this group", "description": "BFS downward through the membership DAG up to `max_depth`.", "tags": [ "Party Group" ], "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "max_depth", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 16 } } ], "responses": { "200": { "description": "Descendant groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "max_depth" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/evaluate": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "post": { "operationId": "evaluatePartyGroupMembership", "summary": "Dry-run evaluate a party against a dynamic group's rule", "description": "Read-only evaluation \u2014 calls the membership-rule evaluator and\nreturns `is_member` plus an explanation summary. Does NOT persist\nmembership. Only valid for `group_type = dynamic`; static groups\nreturn 400. Classification: `intentional_exception` in the\npost-route manifest (POST that doesn't mutate).\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatePartyGroupRequest" } } } }, "responses": { "200": { "description": "Evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/roles": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } ], "get": { "operationId": "listPartyGroupRoles", "summary": "List roles held directly by this group", "description": "Returns roles where this group is the assignee (`assignee_type =\ngroup`). under the governed contract there is NO automatic inheritance \u2014\nthese roles do not flow to member parties.\n", "tags": [ "Party Group" ], "responses": { "200": { "description": "Roles held by the group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupRoleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "assignPartyGroupRole", "summary": "Assign a role to the group", "description": "Assigns a role with the group as assignee. Idempotent via\nIdempotency-Key.\n\nFor role_type=accepted_provider_network:\n- Assignee group must have composition_type=provider_network \u2192 422 INVALID_ASSIGNMENT otherwise.\n- Context entity_type must be product \u2192 context entity_id must reference an\n existing product in the tenant \u2192 404 PRODUCT_CONTEXT_NOT_FOUND if missing.\n- Overlapping active windows on the same (group, role_type, product) tuple\n return 409 NETWORK_ROLE_ALREADY_ACTIVE.\n", "tags": [ "Party Group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignGroupRoleRequest" } } } }, "responses": { "201": { "description": "Role assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyGroupRoleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/party-groups/{id}/roles/{roleId}": { "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "example": "plg_01arz3ndektsv4rrffq69g5fav" } } ], "delete": { "operationId": "revokePartyGroupRole", "summary": "Revoke a role held by the group", "description": "Closes the role assignment with an optional reason supplied as a\nJSON body `{reason: \"...\"}`.\n", "tags": [ "Party Group" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Role revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products": { "post": { "operationId": "createProduct", "summary": "Create a new insurance product", "description": "Create a product definition in the catalogue. Products define the coverage template\nfrom which policies are issued. A product includes coverage sections (covers),\nconfigurable terms, pricing rules, and commission structures.\n\nProducts are created in \"draft\" status and must be explicitly activated before\npolicies can be issued against them.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" }, "examples": { "motor_tpl": { "summary": "Motor third-party liability product (UK)", "value": { "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "description": "Mandatory third-party liability cover for motor vehicles registered in the United Kingdom", "currency": "gbp", "attributes": { "base_premium": 120000, "region": "UK", "regulatory_class": "compulsory", "minimum_age": 17 }, "covers": [ { "code": "TPL-BODILY", "name": "Third-Party Bodily Injury", "description": "Covers liability for bodily injury to third parties arising from vehicle use", "type": "basic", "sum_insured": 1000000, "deductible": 0 }, { "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "description": "Covers liability for damage to third-party property", "type": "basic", "sum_insured": 250000, "deductible": 500 } ], "terms": [ { "code": "POLICY-DURATION", "name": "Policy Duration", "data_type": "integer", "required": true } ] } }, "health_comprehensive": { "summary": "Comprehensive health cover", "value": { "product_code": "HEALTH-COMP-2026", "name": "Comprehensive Health Cover", "type": "health", "description": "Comprehensive health plan covering inpatient, outpatient, dental, and optical care", "currency": "usd", "attributes": { "base_premium": 250000, "scheme_type": "open", "regulatory_registration": "HIC-2026-001" }, "covers": [ { "code": "INPATIENT", "name": "Inpatient Hospital Cover", "description": "Covers hospitalisation, surgery, and ICU stays", "type": "basic", "sum_insured": 5000000, "deductible": 0 }, { "code": "DENTAL", "name": "Dental Cover", "description": "Covers dental consultations, fillings, and extractions", "type": "optional", "sum_insured": 25000, "deductible": 500 } ], "terms": [ { "code": "WAITING-PERIOD-DAYS", "name": "Waiting Period", "data_type": "integer", "required": true } ] } }, "property_commercial": { "summary": "Commercial property insurance (Brazil)", "value": { "product_code": "PROP-COMM-2026", "name": "Seguro Empresarial", "type": "property", "description": "Commercial property insurance covering fire, theft, natural disasters, and business interruption", "currency": "brl", "attributes": { "base_premium": 500000, "market": "LATAM", "susep_code": "0114" }, "covers": [ { "code": "FIRE", "name": "Fire Cover", "description": "Covers damage caused by fire", "type": "basic", "sum_insured": 10000000, "deductible": 5000 } ], "terms": [ { "code": "CONSTRUCTION-TYPE", "name": "Construction Type", "data_type": "string", "required": true } ] } } } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "motor_created": { "summary": "Motor product created in draft status", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "draft", "description": "Mandatory third-party liability cover for motor vehicles registered in the United Kingdom", "currency": "gbp", "attributes": { "base_premium": 120000, "region": "UK", "regulatory_class": "compulsory", "minimum_age": 17 }, "covers": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "TPL-BODILY", "name": "Third-Party Bodily Injury", "type": "basic", "sum_insured": 1000000, "deductible": 0, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "type": "basic", "sum_insured": 250000, "deductible": 500, "status": "active" } ], "terms": [ { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "POLICY-DURATION", "name": "Policy Duration", "data_type": "integer", "required": true } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Product created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listProducts", "summary": "List products", "description": "Retrieve a paginated list of products in the tenant's catalogue.\nResults are sorted by recorded_at descending with a stable cursor\ntiebreaker. Sort order is not configurable.\n\nBoth draft and active products are returned. Use the status field to filter\nif needed (client-side filtering).\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of products to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque product cursor from the previous response meta.next_cursor" } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" }, "examples": { "product_list": { "summary": "Mixed product types", "value": { "data": [ { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "active", "description": "Mandatory third-party liability cover for motor vehicles", "currency": "gbp", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, { "id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "product_code": "HEALTH-COMP-2026", "name": "Comprehensive Health Cover", "type": "health", "status": "active", "description": "Comprehensive health plan covering inpatient, outpatient, dental, and optical care", "currency": "usd", "created_at": "2026-03-11T14:00:00Z", "updated_at": "2026-03-11T14:00:00Z" }, { "id": "542f58e3-8bbd-5c5a-9f6e-d0c506b771cd", "product_code": "LIFE-TERM-2026", "name": "Term Life Assurance", "type": "life", "status": "draft", "description": "Fixed-term life assurance with lump sum death benefit", "currency": "usd", "created_at": "2026-03-10T09:00:00Z", "updated_at": "2026-03-10T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a product by ID", "description": "Retrieve a single product with its full configuration including covers,\nterms, pricing rules, and commission structures.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "full_product": { "summary": "Fully configured liability product", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "LIAB-PROF-2026", "name": "Professional Indemnity Insurance", "type": "liability", "status": "active", "description": "Professional indemnity cover for regulated professionals including legal, accounting, and consulting firms", "currency": "eur", "attributes": { "market": "EMEA", "eligible_professions": [ "legal", "accounting", "consulting", "engineering" ] }, "covers": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "PI-CLAIMS", "name": "Professional Negligence Claims", "type": "basic", "sum_insured": 2000000, "deductible": 5000, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "PI-DEFENCE", "name": "Legal Defence Costs", "type": "basic", "sum_insured": 500000, "deductible": 0, "status": "active" } ], "terms": [ { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "RETRO-DATE", "name": "Retroactive Date", "data_type": "date", "required": true }, { "id": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "code": "RUN-OFF-YEARS", "name": "Run-Off Period", "data_type": "integer", "required": false, "default_value": "6" } ], "pricing_rules": [ { "id": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "name": "Revenue Band Rating", "rule_type": "risk_factor", "base_rate": 0.005, "expression": "revenue_band == 'high' ? 0.008 : 0.005", "status": "active" } ], "commissions": [ { "id": "fa590161-dad2-5a57-84d1-4a71d6457a36", "role_type": "broker", "commission_type": "initial", "rate": 0.15, "calculation_basis": "gross_premium", "status": "active" } ], "created_at": "2026-02-01T10:00:00Z", "updated_at": "2026-03-01T16:00:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateProduct", "summary": "Update a product", "description": "Update an existing product's metadata, attributes, or status.\nProducts can be transitioned from \"draft\" to \"active\" status via this endpoint.\n\nUpdating an active product creates a new version. Existing policies issued under\nprevious versions are not affected.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated display name", "example": "Motor TPL \u2014 Enhanced" }, "description": { "type": "string", "description": "Updated description" }, "status": { "type": "string", "enum": [ "draft", "active" ], "description": "Updated product status" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated extensible attributes (merged with existing)" } }, "additionalProperties": false }, "examples": { "activate_product": { "summary": "Activate a draft product", "value": { "status": "active" } }, "update_metadata": { "summary": "Update product description and attributes", "value": { "description": "Enhanced motor third-party liability with increased bodily injury limits", "attributes": { "max_vehicle_age_years": 15, "minimum_age": 18 } } } } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "examples": { "activated": { "summary": "Product activated", "value": { "data": { "id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "product_code": "MOTOR-TPL-2026", "name": "Motor Third-Party Liability", "type": "motor", "status": "active", "description": "Mandatory third-party liability cover for motor vehicles", "currency": "gbp", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T10:00:00Z" }, "status": "success", "message": "Product updated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/covers": { "get": { "operationId": "getProductCovers", "summary": "Get coverage sections for a product", "description": "Retrieve all coverage sections (covers) defined for a product. Each cover\nincludes its sum insured, deductible, type (basic/optional/rider), and any\nassociated cover provision definitions and terms.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "responses": { "200": { "description": "Covers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverListResponse" }, "examples": { "motor_covers": { "summary": "Motor product coverage sections", "value": { "data": [ { "id": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "code": "TPL-BODILY", "name": "Third-Party Bodily Injury", "description": "Covers liability for bodily injury to third parties", "type": "basic", "sum_insured": 1000000, "deductible": 0, "status": "active" }, { "id": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "code": "TPL-PROPERTY", "name": "Third-Party Property Damage", "description": "Covers liability for damage to third-party property", "type": "basic", "sum_insured": 25000000, "deductible": 50000, "status": "active" }, { "id": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "code": "WINDSCREEN", "name": "Windscreen Cover", "description": "Covers repair or replacement of windscreens and vehicle glass", "type": "optional", "sum_insured": 500000, "deductible": 0, "status": "active" } ], "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "addCover", "summary": "Add a coverage section (cover) to a product", "description": "CRS-3: add a cover to a draft product. The cover may carry nested\n`cover_items` (each with `terms`) and cover-level `cover_terms`, persisted\nas the full canonical cover.* row graph in one atomic transaction. Money\nboundaries are exact integer minor units with a lowercase ISO-4217 currency;\na monetary boundary missing its currency is rejected (422). Co-insurance\npanel splits (basis points) must sum to 10000bp (100%) or the request is\nrejected (422).\n", "tags": [ "Product" ], "security": [ { "BearerAuth": [ "products:write" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCoverRequest" } } } }, "responses": { "201": { "description": "Cover added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "**422 Unprocessable Entity** \u2014 the cover failed a business-rule\nvalidation (unknown cover-item kind, a money boundary missing its\ncurrency, or a co-insurance panel not summing to 10000bp).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "products:write" ], "required_permissions": [ "products:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/pricing-rules": { "post": { "operationId": "assignProductPricingRules", "summary": "Bind a product to a ruleset version for a pipeline stage", "description": "Creates or supersedes the active product\u2194ruleset binding for the given\n`ruleset_type` (pipeline stage). under the governed contract a single product\ncarries one binding per `(tenant context, product_id, ruleset_type,\neffective_from)`; binding a different `ruleset_type` does NOT close the\nprior stage's active row \u2014 supersession is per-stage.\n\n`ruleset_type` is REQUIRED and must be in the canonical allowlist\n(see `400 INVALID_RULESET_TYPE` body for the accepted set). Earlier\nruntime behaviour silently defaulted the field to `claims_assessment`\nat the persistence boundary. The current contract rejects missing or\nunknown values at the HTTP boundary with the accepted set listed in the\nerror body.\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruleset_id", "ruleset_type", "ruleset_version", "effective_from" ], "properties": { "ruleset_id": { "type": "string", "format": "uuid", "description": "ID of the ruleset to bind to the product", "x-axiom-identifier-shape": "uuid" }, "ruleset_type": { "type": "string", "description": "Pipeline stage the binding satisfies. Must be in the canonical\nallowlist; see 400 INVALID_RULESET_TYPE response for the full set.\n", "example": "premium_rating" }, "ruleset_version": { "type": "integer", "minimum": 1, "description": "Version number of the bound ruleset", "example": 1 }, "effective_from": { "type": "string", "format": "date", "description": "Date this binding becomes active (YYYY-MM-DD)", "example": "2026-01-01" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Binding created or superseded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRulesetBindingResponse" }, "examples": { "binding_created": { "summary": "Ruleset binding created", "value": { "data": { "id": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "product_id": "prd_d4e5f6a7b8c90123def0123456789abc", "ruleset_id": "07805e66-69d7-5b42-a978-32729404b560", "ruleset_type": "premium_rating", "ruleset_version": 1, "effective_from": "2026-01-01T00:00:00Z", "created_by": "usr_abc123" }, "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "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.45 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": "listProductPricingRules", "summary": "List product\u2194ruleset bindings (active and historical)", "description": "Returns the binding history for a product in deterministic order\n(effective_from DESC, created_at DESC, id DESC). Each item includes\n`ruleset_type` so callers can distinguish stages without re-querying.\n\nOptional `?ruleset_type=` filter narrows the response to a single\nstage. Unknown values are rejected with 400 INVALID_RULESET_TYPE\n(no silent empty-list).\n", "tags": [ "Product" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" }, { "name": "ruleset_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pipeline stage; must be in the canonical allowlist" } ], "responses": { "200": { "description": "Bindings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRulesetBindingListResponse" }, "examples": { "bindings_list": { "summary": "Active and historical bindings", "value": { "data": [ { "id": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "product_id": "prd_d4e5f6a7b8c90123def0123456789abc", "ruleset_id": "07805e66-69d7-5b42-a978-32729404b560", "ruleset_type": "premium_rating", "ruleset_version": 2, "effective_from": "2026-03-01T00:00:00Z", "created_by": "usr_abc123" }, { "id": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "product_id": "prd_d4e5f6a7b8c90123def0123456789abc", "ruleset_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "ruleset_type": "premium_rating", "ruleset_version": 1, "effective_from": "2026-01-01T00:00:00Z", "effective_to": "2026-03-01T00:00:00Z", "created_by": "usr_abc123" } ], "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "ruleset_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/activate": { "post": { "operationId": "activateProduct", "summary": "Activate a draft product", "description": "Transition a product from draft to active status. The product must have at\nleast one cover and defined terms (with explicit validation bounds) before\nactivation.\n\nThis is a status-only transition: it does NOT re-persist the product's\ncover graph, so it never collides on existing covers (unlike a full\nPUT update). Side effects: persists the status change and emits a formal\nactivation explanation tree (governed contract).\n", "tags": [ "Product" ], "security": [ { "BearerAuth": [ "products:write" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateProductRequest" } } } }, "responses": { "200": { "description": "Product activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "products:write" ], "required_permissions": [ "products:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/products/{id}/audit": { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique product identifier" } ], "get": { "operationId": "getProductsIdAudit", "summary": "Chronological audit feed for a product", "description": "Returns the per-product audit feed in descending performed-at order.\nThe feed is scoped to the admitted tenant context, verifies that the\nproduct exists before reading audit rows, and never returns a silent empty\nfeed for an unknown product identifier.\n\nUse `limit` and `offset` for the current bounded alpha page contract.\nThe runtime default is 50 rows from offset 0.\n", "tags": [ "Product" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Maximum number of audit entries to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Zero-based audit entry offset." } ], "responses": { "200": { "description": "Audit feed for this product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductAuditListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "offset", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "offset", "request_parameters": [ "limit", "offset" ], "consumer_posture": "offset-page", "response_metadata": [ "meta.total", "meta.limit", "meta.offset" ] }, "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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies": { "post": { "operationId": "createPolicy", "summary": "Create a new policy", "description": "Issue a new insurance policy under an active product. The policy is created in\n\"draft\" status by default. At least one party must be assigned (typically the\npolicyholder). Draft policies are not endorsement-eligible; use\n`POST /v1/policies/bind` to create an active, endorsement-eligible policy.\n\nThe product must be in \"active\" status before policies can be issued against it.\nThe effective date must not be in the past (backdating requires special permissions).\n\nSide effects: persists the policy in draft status with assigned parties; emits an audit entry recording the creation.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" }, "examples": { "motor_policy": { "summary": "Motor third-party liability policy (UK)", "value": { "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "vehicle_year": 2023, "sum_insured": 1000000, "territory": "UK" }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "role": "policyholder" }, { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "role": "insured" } ], "created_by": "agent-user-012" } }, "health_policy": { "summary": "Health cover policy", "value": { "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "effective_date": "2026-05-01", "expiry_date": "2027-04-30", "attributes": { "plan_level": "comprehensive", "dependents": 3, "chronic_conditions": [ "diabetes_type_2" ] }, "parties": [ { "party_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "role": "policyholder" }, { "party_id": "4cbb0168-4d04-535d-969b-927f53d9c96c", "role": "dependent" }, { "party_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "role": "beneficiary" } ], "created_by": "broker-portal" } }, "life_policy": { "summary": "Term life assurance (Nigeria)", "value": { "product_id": "542f58e3-8bbd-5c5a-9f6e-d0c506b771cd", "effective_date": "2026-06-01", "expiry_date": "2046-05-31", "attributes": { "sum_assured": 50000000, "currency": "NGN", "smoker_status": "non_smoker" }, "parties": [ { "party_id": "fa633d26-7313-5660-ba5a-3bf7cef790fe", "role": "policyholder" }, { "party_id": "fa633d26-7313-5660-ba5a-3bf7cef790fe", "role": "insured" }, { "party_id": "8a939ebd-5247-5ba8-8312-2a248921d66b", "role": "beneficiary" } ], "created_by": "agent-user-042" } } } } } }, "responses": { "201": { "description": "Policy created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "motor_created": { "summary": "Motor policy created", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "draft", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "vehicle_year": 2023, "sum_insured": 1000000, "territory": "UK" }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "policyholder", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" }, { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "insured", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Policy created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listPolicies", "summary": "List policies", "description": "Retrieve a cursor-paginated list of policies for the tenant.\nResults are sorted by most-recently-recorded first. Sort order is not configurable.\nLegacy `limit` and `offset` query parameters are rejected.\n\nReturns policies across all statuses (draft, quoted, bound, active, lapsed, cancelled, expired).\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of policies to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only policies the party is bound to in any role\n(the party appears in `policy.parties`). Accepts the canonical typed-prefix\nparty id (`pty_\u2026`, governed contract). A malformed value returns 400. Absent =\nall policies for the tenant (current behaviour). Composes with the\nexisting operating-tenant tenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Policies retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyListResponse" }, "examples": { "policy_list": { "summary": "Policies across statuses and verticals", "value": { "data": [ { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-04-01T00:00:00Z" }, { "id": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "policy_number": "POL-2026-000143", "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "status": "cancelled", "effective_date": "2026-03-01", "expiry_date": "2027-02-28", "created_at": "2026-02-28T11:00:00Z", "updated_at": "2026-03-10T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/bind": { "post": { "description": "Bind parties to covers through an active policy version. This contract is the primary policy-creation operation \u2014 it reads party and covers/products context, creates an immutable policy version, and conditionally triggers premium effects. Requires idempotency: callers must supply an idempotency key to prevent duplicate policy creation on retry.", "operationId": "bindPolicy", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBindRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBindResponse" } } }, "description": "Policy bound successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quote not found (QUOTE_NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Idempotency key reused (IDEMPOTENCY_KEY_REUSED)" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quote expired (QUOTE_EXPIRED)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Validation error (PREMIUM_DRIFT_EXCEEDED or POLICY_NOT_YET_EFFECTIVE_FOR_BIND)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Server Error" } }, "security": [ { "BearerAuth": [ "policies:bind" ] } ], "summary": "Bind Policy", "tags": [ "Policy" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "policies:bind" ], "required_permissions": [ "policies:bind" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}": { "get": { "operationId": "getPolicy", "summary": "Get a policy by ID", "description": "Retrieve a single policy with its full details including assigned parties\nand premium schedule.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "active_policy": { "summary": "Active motor policy with parties and premiums", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "attributes": { "vehicle_registration": "AB12 CDE", "vehicle_make": "Volkswagen", "vehicle_model": "Golf", "sum_insured": 1000000 }, "parties": [ { "party_id": "07805e66-69d7-5b42-a978-32729404b560", "party_type": "individual", "role": "policyholder", "status": "active", "assigned_at": "2026-03-12T08:00:00Z" } ], "premiums": [ { "id": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "amount": 11500, "due_date": "2026-04-01", "status": "paid", "payment_method": "debit_order" }, { "id": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "amount": 11500, "due_date": "2026-05-01", "status": "pending", "payment_method": "debit_order" } ], "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-04-01T00:00:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/versions": { "post": { "operationId": "createPolicyVersion", "summary": "Create a new policy version", "description": "Create a new version snapshot of the policy. Policy versions provide an immutable\nrecord of the policy state at each point in time, supporting \"as-was\" semantics\nrequired for claims adjudication and regulatory reporting.\n\nEach version captures the complete policy state including attributes, parties,\nand coverage details at the time of creation.\n\nSide effects: not yet implemented. Returns 501.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "effective_date" ], "properties": { "effective_date": { "type": "string", "format": "date", "description": "Date from which this version takes effect", "example": "2026-06-01" }, "reason": { "type": "string", "description": "Reason for creating a new version", "example": "Mid-term adjustment following endorsement END-001" }, "created_by": { "type": "string", "description": "Identifier of the user or service creating this version", "example": "underwriter-user-003" } }, "additionalProperties": false }, "examples": { "endorsement_version": { "summary": "Version created after endorsement", "value": { "effective_date": "2026-06-01", "reason": "Mid-term adjustment \u2014 sum insured increase from 250,000 to 300,000", "created_by": "underwriter-user-003" } }, "renewal_version": { "summary": "Version created at renewal", "value": { "effective_date": "2027-04-01", "reason": "Annual renewal \u2014 updated premium and vehicle value", "created_by": "renewal-system" } } } } } }, "responses": { "201": { "description": "Policy version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionResponse" }, "examples": { "version_created": { "summary": "New policy version", "value": { "data": { "id": "pov_4d5e6f7a8b9c0123defa234567890123", "policy_id": "pol_1a2b3c4d5e6f7890abcdef1234567890", "version_number": 2, "version_type": "endorsement", "effective_from": "2026-06-01T00:00:00Z", "effective_to": null, "change_reason": "Mid-term adjustment \u2014 sum insured increase from 250,000 to 300,000", "created_by": "underwriter-user-003", "previous_version": "pov_1a2b3c4d5e6f7890abcdef1234567890", "created_at": "2026-05-28T14:00:00Z" }, "status": "success", "message": "Policy version created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listPolicyVersions", "summary": "List policy version snapshots", "description": "Return every immutable version snapshot for the policy, ordered by\nversion_number ascending.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy versions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/issue": { "post": { "operationId": "issuePolicy", "summary": "Issue a draft policy", "description": "Transition a policy from draft to bound status. The policy must have at\nleast one party with the policyholder role assigned.\n\nSide effects: persists the status change and emits an audit entry with\noperation code policy.issue in a single transaction.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "issued_by" ], "properties": { "issued_by": { "type": "string", "description": "Identifier of the user or service issuing the policy" }, "notes": { "type": "string", "description": "Optional notes for the issue action" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Policy issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "issued": { "summary": "Draft policy bound", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "bound", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-20T10:00:00Z" }, "status": "success", "message": "Policy issued successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/activate": { "post": { "operationId": "activatePolicy", "summary": "Activate a bound policy", "description": "Transition a policy from bound to active status. The policy's effective\ndate must be in the past or present (effective_date <= now).\n\nSide effects: persists the status change and emits an audit entry with\noperation code policy.activate in a single transaction.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "activated_by" ], "properties": { "activated_by": { "type": "string", "description": "Identifier of the user or service activating the policy" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Policy activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" }, "examples": { "activated": { "summary": "Issued policy activated", "value": { "data": { "id": "204a5555-2273-5dfd-8bcc-09717add6538", "policy_number": "POL-2026-000142", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "status": "active", "effective_date": "2026-04-01", "expiry_date": "2027-03-31", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-20T10:30:00Z" }, "status": "success", "message": "Policy activated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/allocation-simulations": { "post": { "operationId": "createAllocationSimulation", "summary": "Simulate an allocation breakdown", "description": "Validates a proposed allocation breakdown without persisting it.\nAccepts only simulation_preview as trigger. Returns 422 for semantic\nvalidation failures (sum mismatch, missing rule_id, invalid inputs).\n\nEach operation in the request specifies a benefit change (add, remove,\nchange) with proposed allocation values in allocation_inputs.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Policy identifier" } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "allocation-simulations" ] }, "attributes": { "type": "object", "required": [ "trigger", "operations" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "Optional point-in-time for simulation context" }, "base_policy_version_id": { "type": "string", "format": "uuid", "description": "Optional base policy version override", "x-axiom-identifier-shape": "uuid" }, "trigger": { "type": "string", "enum": [ "simulation_preview" ] }, "operations": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "op", "benefit_id" ], "properties": { "op": { "type": "string", "enum": [ "add_benefit", "remove_benefit", "change_benefit" ] }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "allocation_inputs": { "type": "object", "description": "Proposed allocation values for validation", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Proposed allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Simulation completed successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "allocation-simulations" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "properties": { "benefit_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string" }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "simulated": { "type": "boolean" }, "calculation_version": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (wrong content type, missing fields)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "404": { "description": "Policy not found (POLICY_NOT_FOUND)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "409": { "description": "Version conflict \u2014 no resolvable base policy version (VERSION_CONFLICT)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "422": { "description": "Semantic validation failure (sum mismatch, missing rule_id, invalid trigger)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/allocation-history": { "get": { "operationId": "listPolicyAllocationHistory", "summary": "List temporal allocation history for a policy", "description": "Returns cursor-paginated temporal allocation snapshots for all premiums\nin a policy. Ordered by effective_from DESC, created_at DESC, premium_id ASC.\nUses half-open [effective_from, effective_to) temporal semantics under the governed contract.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Policy identifier" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of resources per page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for forward pagination (allocation ID)" }, { "name": "page[before]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for backward pagination (allocation ID)" } ], "responses": { "200": { "description": "Allocation history retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "policy-allocation-history-entries" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "premium_id", "benefit_id", "amount", "allocation_percentage_bps", "allocation_basis", "calculation_version", "effective_from", "trigger" ], "properties": { "premium_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32" }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (missing policy id)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]", "page[before]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/endorsements": { "post": { "operationId": "createEndorsement", "summary": "Create a policy endorsement", "description": "Submit an endorsement (mid-term adjustment) to an **active** policy. Endorsements\nrecord structured changes to the policy terms, coverage, or parties.\nThe policy must be in `active` status; endorsing a `draft` or other non-active\npolicy returns HTTP 422 with code `INVALID_STATE_TRANSITION`.\n\nEach endorsement receives a sequential number within the policy (END-001, END-002, etc.)\nand triggers the creation of a new policy version when applied.\n\nSide effects: creates a new immutable policy version and persists party-role\nchanges when `change_type=parties`. Emits an audit entry when audit is configured.\n\nCommon endorsement types:\n- amendment: Modify existing terms (e.g. change address, increase sum insured)\n- addition: Add new coverage or parties\n- deletion: Remove coverage or parties\n- correction: Fix data entry errors\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "change_type", "description", "endorsed_by" ], "properties": { "change_type": { "type": "string", "description": "Classification of the endorsement change", "enum": [ "parties", "coverages", "terms", "premium" ], "example": "coverages" }, "description": { "type": "string", "description": "Human-readable description of the changes", "example": "Increase sum insured from R250,000 to R300,000 and update insured address" }, "new_parties": { "type": "array", "items": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string" } }, "additionalProperties": false }, "description": "New parties to add (for change_type 'parties')" }, "updated_attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Structured representation of attribute changes", "example": { "sum_insured": { "from": 250000, "to": 300000 }, "address": { "from": "42 Baker Street, London", "to": "18 Regent Street, London" } } }, "endorsed_by": { "type": "string", "description": "Identifier of the user or process creating the endorsement", "example": "underwriter-user-003" }, "effective_at": { "type": "string", "format": "date-time", "description": "Effective timestamp for party endorsements (change_type=parties).\nMust not be retroactive. Required when change_type=parties.\n" }, "party_changes": { "type": "array", "description": "Party mutations for change_type=parties endorsements. Each entry\nspecifies an operation (add/revoke/replace), party_id, and role.\n", "items": { "type": "object", "required": [ "op", "party_id", "role" ], "properties": { "op": { "type": "string", "enum": [ "add", "revoke", "replace" ] }, "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "examples": { "increase_sum_insured": { "summary": "Increase motor policy sum insured", "value": { "change_type": "coverages", "description": "Increase vehicle insured value following market revaluation", "updated_attributes": { "sum_insured": { "from": 350000, "to": 420000 }, "monthly_premium": { "from": 1850, "to": 2150 } }, "endorsed_by": "underwriter-user-003" } }, "add_driver": { "summary": "Add named driver to motor policy", "value": { "change_type": "parties", "description": "Add spouse as named driver with full driving history", "new_parties": [ { "party_id": "party-jane-smith-001", "role": "insured" } ], "updated_attributes": { "named_drivers": { "added": [ { "name": "Jane Smith", "licence_number": "SMITH801010JA9AB", "years_driving": 12 } ] } }, "endorsed_by": "agent-user-012" } } } } } }, "responses": { "201": { "description": "Endorsement created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndorsementResponse" }, "examples": { "endorsement_created": { "summary": "Endorsement pending application", "value": { "data": { "id": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "policy_id": "204a5555-2273-5dfd-8bcc-09717add6538", "endorsement_number": "END-001", "type": "amendment", "description": "Increase vehicle insured value following market revaluation", "effective_date": "2026-07-01", "status": "pending", "changes": { "sum_insured": { "from": 350000, "to": 420000 }, "monthly_premium": { "from": 1850, "to": 2150 } }, "endorsed_by": "underwriter-user-003", "created_at": "2026-06-25T14:00:00Z" }, "status": "success", "message": "Endorsement created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listEndorsements", "summary": "List policy endorsements", "description": "Return the policy's endorsements, ordered by version_number ascending.\nEndorsements are stored as policy version snapshots (no separate entity);\nthis list is the policy's versions filtered to version_type == endorsement.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" } ], "responses": { "200": { "description": "Policy endorsements retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyVersionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/policies/{id}/certificates/{party_id}": { "get": { "operationId": "getCertificate", "summary": "Get member certificate projection", "description": "Retrieve a read-only certificate of insurance for a specific member on a\ngroup policy. Resolves the effective policy version and active roles at the\n`as_of` timestamp (defaults to now). Returns the master policy_id, party_id,\nrole list, effectivity window, and pinned version_id.\n\nNo persistence side effects \u2014 this is a pure read projection.\n\nReturns 404 if the party is unknown or inactive at the given `as_of` time.\n", "tags": [ "Policy" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique policy identifier" }, { "name": "party_id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Identifier of the member party" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time for certificate resolution (defaults to now)" } ], "responses": { "200": { "description": "Certificate projection retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateResponse" }, "examples": { "member_certificate": { "summary": "Active member certificate", "value": { "data": { "policy_id": "pol_1a2b3c4d5e6f7890abcdef1234567890", "party_id": "par_a1b2c3d4e5f67890abcdef1234567890", "version_id": "pov_4d5e6f7a8b9c0123defa234567890123", "roles": [ "policyholder", "insured" ], "effective_from": "2026-04-01T00:00:00Z", "effective_to": null }, "status": "success", "message": "Certificate retrieved successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims": { "post": { "description": "Contract authority for POST /v1/claims (submitClaim) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "submitClaim", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:write" ] } ], "summary": "Submit Claim", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:write" ], "required_permissions": [ "claims:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 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": { "description": "Contract authority for GET /v1/claims (listClaims) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "listClaims", "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "List Claims", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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.45 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": "standard", "scopes": [ "claims:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}": { "get": { "description": "Contract authority for GET /v1/claims/{id} (getClaim) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getClaim", "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.45 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": "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "Get Claim", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/assess": { "post": { "description": "Contract authority for POST /v1/claims/{id}/assess (assessClaim) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "assessClaim", "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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:write" ] } ], "summary": "Assess Claim", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:write" ], "required_permissions": [ "claims:write" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/authorisations": { "post": { "operationId": "recordClaimAuthorisation", "summary": "Record a claim authorisation", "description": "Record an governed contract authorisation sub-event against a claim. The row is\nappend-only and carries the authorising actor, authorised scope, budget,\ngoverning-version binding, optional compliance state, decision date, and\nexplanation-node reference.\n\nClaim payments may cite the returned authorisation id. When they do, the\npayment path runs the authorisation compliance gate before disbursement.\n\nSide effects: persists an `authorisation_transitions` row under the\ntenant context and returns the recorded authorisation.\n", "tags": [ "Claim" ], "security": [ { "BearerAuth": [ "claims:authorise" ] } ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationRequest" }, "examples": { "medical_pre_auth": { "summary": "Medical service authorisation", "value": { "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "budget_minor": 250000, "budget_currency_code": "zar", "governing_version_kind": "catalogue", "governing_version_row_id": "b1468ab8-97c1-5aa6-aca6-9430e182a5bd", "decision_date": "2026-07-06T10:00:00Z", "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346" } } } } } }, "responses": { "201": { "description": "Claim authorisation recorded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordClaimAuthorisationResponse" }, "examples": { "recorded": { "summary": "Recorded authorisation", "value": { "data": { "id": "3e3402e5-6a38-5c2f-b846-93ac5e198cde", "logical_authorisation_id": "a1699eac-cf08-52d7-be4d-242049b373f5", "entity_type": "claim", "entity_id": "07805e66-69d7-5b42-a978-32729404b560", "transition_kind": "authorisation-granted", "authorisation_kind": "pre-auth", "authorising_actor": "c6240249-09af-5036-8295-d43ef1b181ea", "authorised_scope": { "procedure_code": "1234", "visit_limit": 3 }, "budget_minor": 250000, "budget_currency_code": "zar", "decision_date": "2026-07-06T10:00:00Z", "explanation_node_id": "bef0fb27-f305-55ac-84a3-cf528da03346", "valid_from": "2026-07-06T10:00:00Z", "asserted_from": "2026-07-06T10:00:00Z" }, "status": "success", "message": "Claim authorisation recorded successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "claims:authorise" ], "required_permissions": [ "claims:authorise" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 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": { "description": "Contract authority for POST /v1/claims/{id}/pay (payClaim) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "payClaim", "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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:pay" ] } ], "summary": "Pay Claim", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:pay" ], "required_permissions": [ "claims:pay" ], "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.45 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", "summary": "Close a claim", "description": "Close a claim through the runtime claim service. The handler enforces\ntenant context, typed claim IDs, actor attribution, and terminal-state\ntransition checks before 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.45 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" } } } }, "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" } }, "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.45 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.45 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.45 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": { "description": "Contract authority for POST /v1/claims/{id}/reserves (createReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "createReserve", "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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:reserve" ] } ], "summary": "Create Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:reserve" ], "required_permissions": [ "claims:reserve" ], "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.45 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": { "description": "Contract authority for GET /v1/claims/{id}/reserves (listClaimReserves) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "listClaimReserves", "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.45 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": "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "List Claim Reserves", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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.45 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": "standard", "scopes": [ "claims:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/reserves/{reserveId}": { "get": { "description": "Contract authority for GET /v1/claims/{id}/reserves/{reserveId} (getReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getReserve", "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.45 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": "Path parameter `reserveId`.", "in": "path", "name": "reserveId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "Get Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "patch": { "description": "Contract authority for PATCH /v1/claims/{id}/reserves/{reserveId} (updateReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "updateReserve", "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.45 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": "Path parameter `reserveId`.", "in": "path", "name": "reserveId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:reserve" ] } ], "summary": "Update Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:reserve" ], "required_permissions": [ "claims:reserve" ], "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.45 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": { "description": "Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/release (releaseReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "releaseReserve", "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.45 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": "Path parameter `reserveId`.", "in": "path", "name": "reserveId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:reserve" ] } ], "summary": "Release Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:reserve" ], "required_permissions": [ "claims:reserve" ], "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.45 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": { "description": "Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/cancel (cancelReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "cancelReserve", "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.45 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": "Path parameter `reserveId`.", "in": "path", "name": "reserveId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:reserve" ] } ], "summary": "Cancel Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:reserve" ], "required_permissions": [ "claims:reserve" ], "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.45 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": { "description": "Contract authority for POST /v1/claims/{id}/reserves/{reserveId}/reestablish (reestablishReserve) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "reestablishReserve", "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.45 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": "Path parameter `reserveId`.", "in": "path", "name": "reserveId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:reserve" ] } ], "summary": "Reestablish Reserve", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:reserve" ], "required_permissions": [ "claims:reserve" ], "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.45 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": { "description": "Contract authority for GET /v1/claims/reserves (listPolicyReserves) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "listPolicyReserves", "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "List Policy Reserves", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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.45 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": "standard", "scopes": [ "claims:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/investigations": { "post": { "description": "Contract authority for POST /v1/claims/{id}/investigations (createOrAdvanceInvestigation) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "createOrAdvanceInvestigation", "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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:investigate" ] } ], "summary": "Create Or Advance Investigation", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:investigate" ], "required_permissions": [ "claims:investigate" ], "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.45 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": { "description": "Contract authority for POST /v1/claims/{claimId}/recoveries (createRecovery) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "createRecovery", "parameters": [ { "description": "Path parameter `claimId`.", "in": "path", "name": "claimId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:recover" ] } ], "summary": "Create Recovery", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:recover" ], "required_permissions": [ "claims:recover" ], "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.45 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": { "description": "Contract authority for POST /v1/claims/{claimId}/recoveries/{recoveryId}/corrections (createCorrection) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "createCorrection", "parameters": [ { "description": "Path parameter `claimId`.", "in": "path", "name": "claimId", "required": true, "schema": { "type": "string" } }, { "description": "Path parameter `recoveryId`.", "in": "path", "name": "recoveryId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:recover" ] } ], "summary": "Create Correction", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:recover" ], "required_permissions": [ "claims:recover" ], "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.45 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}/settlement-statements/{decisionId}": { "get": { "description": "Contract authority for GET /v1/claims/{id}/settlement-statements/{decisionId} (getClaimSettlementStatement) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getClaimSettlementStatement", "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.45 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": "Path parameter `decisionId`.", "in": "path", "name": "decisionId", "required": true, "schema": { "type": "string" } }, { "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "claims:read" ] } ], "summary": "Get Claim Settlement Statement", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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:read" ], "required_permissions": [ "claims: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/assertions": { "get": { "description": "Contract authority for GET /v1/assertions (listAssertions) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "listAssertions", "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "assertions:read" ] } ], "summary": "List Assertions", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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.45 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": "standard", "scopes": [ "assertions:read" ], "required_permissions": [ "assertions: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/assertions/{id}": { "get": { "description": "Contract authority for GET /v1/assertions/{id} (getAssertion) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getAssertion", "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.45 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": "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "assertions:read" ] } ], "summary": "Get Assertion", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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": [ "assertions:read" ], "required_permissions": [ "assertions: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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums": { "get": { "operationId": "listPremiums", "summary": "List premiums", "description": "Retrieve a paginated list of aggregate premium records for the operating\ntenant (one Premium per policy, the contract model). Cursor-paginated with\n`page[size]` default 20 / max 100 and opaque `page[after]` cursors.\nLegacy `limit` and `offset` query parameters are rejected.\n\nThe `policy_id` / `party_id` filter parameters are validated fail-loud (a\nmalformed typed-prefix value returns `400`, governed contract); they compose with the\noperating-tenant tenant-isolated scope, never widen it.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of premiums to return in this cursor page" }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as meta.next_cursor by the previous page" }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only premiums for this policy.\nAccepts the canonical typed-prefix policy id (`pol_\u2026`, governed contract).\nA malformed value returns 400. Absent = all premiums for the tenant.\nComposes with the existing operating-tenant tenant-isolated scope; never widens it.\n" }, { "name": "party_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only premiums owed by this party (the premium\ndebtor / policyholder). Accepts the canonical typed-prefix party id\n(`pty_\u2026`, governed contract). A malformed value returns 400. Absent = all\npremiums for the tenant. Composes with the existing operating-tenant\ntenant-isolated scope; never widens it.\n" } ], "responses": { "200": { "description": "Premiums retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumListResponse" }, "examples": { "premium_list": { "summary": "Aggregate premiums across policies", "value": { "data": [ { "id": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "active", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 12, "installment_amount_minor": 10417, "payment_frequency": "monthly", "effective_date": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" }, { "id": "f5550bad-c878-56c6-a82d-622720f34dcc", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "premium_type": "renewal", "status": "draft", "currency": "gbp", "base_premium": 9550, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 9550, "final_premium": 9550, "installment_count": 1, "installment_amount_minor": 9550, "payment_frequency": "annual", "effective_date": "2026-02-15T00:00:00Z", "created_at": "2026-01-15T00:00:00Z", "updated_at": "2026-01-15T00:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "party_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPremium", "summary": "Create a premium record", "description": "Persist a new aggregate premium (inflow-obligation) record for a policy and\nreturn it with `201 Created`. Exactly one Premium exists per policy\n(the (tenant context, policy_id) uniqueness constraint, the contract model) \u2014 a create for a policy\nthat already has a premium fails loud with `409 Conflict`.\n\nThis persists a manually-entered / imported inflow-obligation record at\n`status=draft`. It is NOT a rated premium decision \u2014 the rated path is\n`POST /v1/premiums/calculate`, which evaluates versioned CEL rules and emits\nan explanation tree. A draft obligation carries no rating decision to\nexplain (platform principle untouched).\n\nThe premium is scoped to the operating tenant \u2014 `tenant context` is taken from the\ntenant-context, never the request body. Intentional defaults applied on\ncreate (documented, not silent): `status=draft`, `premium_type` defaults to\n`initial`, and an unrated draft sets `base_premium = net_premium =\nfinal_premium = amount.amount_minor` (no discounts/commission yet, contract rule).\n\nIdempotent via the `Idempotency-Key` header: same key + same body returns the\noriginal `201`; same key + different body returns `409`.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "amount" ], "properties": { "policy_id": { "type": "string", "description": "Reference to the policy this premium belongs to, in the canonical\ntyped-prefix form (`pol_\u2026`, governed contract). A bare UUID is also\naccepted. A malformed value returns 400.\n", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Premium amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "premium_type": { "type": "string", "description": "Optional classifier on the aggregate premium (defaults to\n`initial` when omitted, contract rule). E.g. `initial`, `renewal`,\n`endorsement`, `adjustment`.\n", "example": "initial" }, "party_id": { "type": "string", "description": "Optional reference to the party who owes this premium, in the\ncanonical typed-prefix form (`pty_\u2026`, governed contract). A bare UUID is\nalso accepted. A malformed value returns 400.\n", "example": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "examples": { "monthly_debit_order": { "summary": "Draft inflow obligation (ZAR)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "amount": { "amount_minor": 125000, "currency_code": "zar" }, "premium_type": "initial" } }, "endorsement_adjustment": { "summary": "Endorsement premium adjustment (UK)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "amount": { "amount_minor": 2250, "currency_code": "gbp" }, "premium_type": "endorsement" } }, "with_party": { "summary": "Annual premium with explicit debtor party (Japan)", "value": { "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0c", "amount": { "amount_minor": 48000000, "currency_code": "jpy" }, "premium_type": "renewal", "party_id": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a" } } } } } }, "responses": { "201": { "description": "Premium created and persisted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumResponse" }, "examples": { "premium_created": { "summary": "Draft premium created", "value": { "data": { "id": "db6f76d9-4b0b-5ac0-ae58-3bc9564b5f8f", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "draft", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 1, "installment_amount_minor": 125000, "payment_frequency": "annual", "effective_date": "2026-03-12T08:00:00Z", "created_at": "2026-03-12T08:00:00Z", "updated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Premium created successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}": { "get": { "operationId": "getPremium", "summary": "Get a premium by ID", "description": "Retrieve a single premium record by its unique identifier.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique premium identifier" } ], "responses": { "200": { "description": "Premium retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumResponse" }, "examples": { "active_premium": { "summary": "Active aggregate premium", "value": { "data": { "id": "e70f8626-562d-58ed-b6a0-ca46a5ce7627", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "party_id": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "premium_type": "initial", "status": "active", "currency": "zar", "base_premium": 125000, "total_discount": 0, "total_surcharge": 0, "tax_amount": 0, "net_premium": 125000, "final_premium": 125000, "installment_count": 12, "installment_amount_minor": 10417, "payment_frequency": "monthly", "effective_date": "2026-01-01T00:00:00Z", "due_date": "2026-04-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-03-02T08:30:00Z" }, "status": "success" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 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/calculate": { "post": { "operationId": "calculatePremium", "summary": "Calculate a premium quotation", "description": "Calculate a premium quotation for a given product and risk profile. This is a\nread-only operation that does not create any records -- it returns the calculated\npremium breakdown including base premium, adjustments, commissions, and totals.\n\nThe calculation uses the product's configured pricing rules and evaluates them\nagainst the provided risk factors. Each adjustment is itemised with the rule\nname and human-readable explanation for full transparency.\n\nOn the CEL pricing path (triggered by `effective_date` in rating_inputs), commission\nis derived from versioned CEL rules classified as `entity_type=pricing` and\n`rule_type=commission_rate` within the same ruleset binding. When no commission rule\nexists for the resolved product and effective date, commission is zero and the\ncommissions list is empty; legacy product JSON is not consulted. Commission amounts\nare exact `int64` minor units; float outputs are rejected.\n\nThis endpoint supports quoting workflows where the premium is calculated before\na policy is issued.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "product_id", "rating_inputs" ], "properties": { "policy_id": { "type": "string", "description": "Reference to the policy being priced. Required for CEL context assembly.", "example": "pol-001", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "format": "uuid", "description": "Reference to the product to calculate premium for", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "rating_inputs": { "type": "object", "additionalProperties": true, "description": "Rating inputs for premium calculation. When `effective_date` is present\n(RFC3339 format), the CEL-based pricing path is used with as-was binding\nresolution. Without `effective_date`, the legacy pricing path applies.\n", "properties": { "effective_date": { "type": "string", "format": "date-time", "description": "As-was timestamp for binding resolution (RFC3339). Required for CEL path.\nWhen present, triggers CEL-based premium calculation with versioned\nruleset resolution under the governed contract.\n", "example": "2026-04-01T00:00:00Z" }, "risk_profile": { "type": "object", "additionalProperties": true, "description": "Risk profile data for CEL evaluation (varies by product type)" } }, "example": { "effective_date": "2026-04-01T00:00:00Z", "risk_profile": { "driver_age": 28, "vehicle_value": 350000, "claims_history": 0 } } } }, "additionalProperties": false }, "examples": { "motor_quote_cel": { "summary": "Motor TPL premium calculation (CEL path)", "value": { "policy_id": "pol-motor-001", "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "rating_inputs": { "effective_date": "2026-04-01T00:00:00Z", "risk_profile": { "driver_age": 28, "vehicle_value": 350000, "vehicle_make": "Volkswagen", "vehicle_model": "Polo", "vehicle_year": 2023, "claims_history": 0, "no_claims_bonus_years": 3, "state": "New York", "parking_type": "secure_garage" } } } }, "health_quote_cel": { "summary": "Health cover premium calculation (CEL path)", "value": { "policy_id": "pol-health-001", "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "rating_inputs": { "effective_date": "2026-05-01T00:00:00Z", "risk_profile": { "primary_age": 35, "dependents": 2, "dependent_ages": [ 32, 5 ], "smoker": false, "plan_level": "comprehensive" } } } }, "legacy_quote": { "summary": "Legacy premium calculation (no effective_date)", "value": { "policy_id": "pol-legacy-001", "product_id": "542f58e3-8bbd-5c5a-9f6e-d0c506b771cd", "rating_inputs": { "driver_age": 35, "vehicle_value": 200000 } } } } } } }, "responses": { "200": { "description": "Premium calculated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumCalculationResponse" }, "examples": { "motor_calculation": { "summary": "Motor premium breakdown", "value": { "data": { "product_id": "e74fc507-ba17-5540-871a-0b04cdb6727b", "base_premium": { "amount_minor": 1200000, "currency_code": "usd" }, "total_premium": { "amount_minor": 1380000, "currency_code": "usd" }, "gross_premium": { "amount_minor": 1380000, "currency_code": "usd" }, "discount_total": { "amount_minor": 0, "currency_code": "usd" }, "net_premium": { "amount_minor": 1380000, "currency_code": "usd" }, "adjusted_premium": { "amount_minor": 1380000, "currency_code": "usd" }, "final_premium": { "amount_minor": 1380000, "currency_code": "usd" }, "adjustments": [ { "rule_name": "young_driver_loading", "adjustment": 180000, "description": "Young driver loading \u2014 primary driver age 28, 15% applied to base premium" }, { "rule_name": "no_claims_discount", "adjustment": -120000, "description": "No-claims discount \u2014 3 years claim-free, 10% discount applied" }, { "rule_name": "urban_risk_loading", "adjustment": 120000, "description": "Geographical risk loading \u2014 New York state, 10% applied" } ], "discounts": [], "commissions": [ { "role_type": "broker", "amount": 207000, "commission_type": "initial" } ], "calculated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Premium calculated successfully" } }, "health_with_discount": { "summary": "Health premium with group discount", "value": { "data": { "product_id": "1ff66716-4d9b-5d28-bd1b-a684c530fbda", "base_premium": { "amount_minor": 350000, "currency_code": "usd" }, "total_premium": { "amount_minor": 595000, "currency_code": "usd" }, "gross_premium": { "amount_minor": 595000, "currency_code": "usd" }, "discount_total": { "amount_minor": 29750, "currency_code": "usd" }, "net_premium": { "amount_minor": 565250, "currency_code": "usd" }, "adjusted_premium": { "amount_minor": 595000, "currency_code": "usd" }, "final_premium": { "amount_minor": 565250, "currency_code": "usd" }, "adjustments": [ { "rule_name": "dependent_loading", "adjustment": 210000, "description": "Dependent loading \u2014 1 adult dependent (140000 cents) + 1 child dependent (70000 cents)" }, { "rule_name": "non_smoker_discount", "adjustment": -35000, "description": "Non-smoker discount \u2014 10% applied to primary policyholder base" }, { "rule_name": "age_band_adjustment", "adjustment": 70000, "description": "Age band 30-39 \u2014 20% loading on base premium" } ], "discounts": [ { "group_id": "grp-family-001", "rule_id": "rule-fam-disc-v1", "rule_version": 1, "amount": 29750, "composition_included": true, "description": "Group discount: Family Plan (rule rule-fam-disc-v1 v1)" } ], "commissions": [ { "role_type": "broker", "amount": 59500, "commission_type": "initial" } ], "calculated_at": "2026-03-12T08:00:00Z" }, "status": "success", "message": "Premium calculated successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Actor attribution is missing or invalid. Premium calculation requires\nan authenticated actor and tenant context before a rated decision can\nbe evaluated.\n", "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation error from CEL premium calculation path. Possible error codes:\n- `EFFECTIVE_DATE_REQUIRED` \u2014 `rating_inputs.effective_date` is missing\n- `EFFECTIVE_DATE_INVALID` \u2014 `rating_inputs.effective_date` is not valid RFC3339\n- `PRICING_RULESET_NOT_FOUND_AS_OF` \u2014 no active pricing ruleset at `effective_date`\n- `RULE_CONTEXT_MISSING` \u2014 required evaluation fact is absent\n- `PREMIUM_RULE_OUTPUT_INVALID` \u2014 CEL rule returned non-exact financial output\n- `PREMIUM_CEL_DEPS_MISSING` \u2014 CEL pipeline dependencies not configured\n- `GROUP_DISCOUNT_OUTPUT_INVALID` \u2014 group discount rule returned float, negative, or malformed output\n- `DISCOUNT_COMPOSITION_REQUIRED` \u2014 no tenant or system discount composition rule found\n- `DISCOUNT_COMPOSITION_INVALID` \u2014 composition rule returned unsupported mode or negative result\n- `DISCOUNT_TOTAL_EXCEEDS_GROSS` \u2014 composed discount total exceeds gross premium\n- `BILLING_PERIOD_ANCHOR_REQUIRED` \u2014 forward-only enforcement cannot resolve next billing anchor\n- `COMMISSION_PARTICIPANT_REQUIRED` \u2014 distribution chain empty, no participants for split\n- `COMMISSION_SPLIT_RULE_OUTPUT_INVALID` \u2014 split rule returned unknown parties, negative/zero shares, or malformed output\n- `COMMISSION_SPLIT_UNBALANCED` \u2014 split shares sum does not equal total commission\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "effective_date_required": { "summary": "Missing effective_date", "value": { "errors": [ { "status": "422", "code": "EFFECTIVE_DATE_REQUIRED", "title": "Validation Error", "detail": "effective_date is required for premium calculation under the governed contract" } ] } }, "effective_date_invalid": { "summary": "Invalid effective_date format", "value": { "errors": [ { "status": "422", "code": "EFFECTIVE_DATE_INVALID", "title": "Validation Error", "detail": "effective_date is not valid RFC3339: parsing time \"not-a-date\"" } ] } }, "ruleset_not_found": { "summary": "No pricing ruleset at effective_date", "value": { "errors": [ { "status": "422", "code": "PRICING_RULESET_NOT_FOUND_AS_OF", "title": "Validation Error", "detail": "no active pricing ruleset at requested effective_date" } ] } } } } } }, "500": { "description": "Internal error from premium calculation. Internal failures are returned\nthrough the standard error envelope without exposing infrastructure\ndetails to public clients.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "Internal calculation failure", "value": { "errors": [ { "status": "500", "code": "SERVER_ERROR", "title": "Server Error", "detail": "Failed to calculate premium" } ] } } } } } } }, "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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}/cancellation-refunds": { "post": { "operationId": "postPremiumCancellationRefund", "summary": "Post a balanced premium cancellation refund", "description": "Computes the cancellation return-premium for the supplied policy/event using\nthe as-was product ruleset binding (governed contract). Non-zero refunds post a\nbalanced `premium_refund` ledger transaction (governed contract) \u2014 one\ndebit against `premium-income` and one credit against\n`premium-refund-payable`. Zero-refund decisions persist an explanation tree\nand return an empty ledger entry list without fabricating ledger rows. The\nrefund amount is calculated by the configured method on the binding:\n`pro_rata`, `short_rate`, or `minimum_earned`. All amounts are exact int64\nminor units; basis points are int64 (governed contract).\n\nThe same call durably persists an AC-7 explanation tree (governed contract). For\nnon-zero refunds the tree is persisted in the same transaction as\nthe ledger entries; the persisted tree's ID is stamped on both ledger legs\nas `explanation_tree_id`.\n\nIdempotency is keyed strictly on the client-supplied `Idempotency-Key`\nheader (governed contract). Replays return `200 OK` with `is_replay=true` and the\noriginal transaction's ledger entry IDs; first-posts return `201 Created`.\nAn empty `Idempotency-Key` returns 422 `IDEMPOTENCY_KEY_REQUIRED`.\n\nCancellation return premium (pro-rata, short-rate, minimum-earned).\nAll required inputs and\nconfiguration must be present and well-formed; missing or malformed\ncancellation_refund.* keys surface as typed 422 errors with stable codes.\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Unique premium identifier" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Client-supplied idempotency key (governed contract). Required. The server\nderives the per-leg ledger row keys as `{Idempotency-Key}:debit` and\n`{Idempotency-Key}:credit`. Replays of the same key return the\noriginal transaction with `is_replay=true` and write no new rows.\n" } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-cancellation-refunds" ] }, "attributes": { "type": "object", "required": [ "policy_id", "product_id", "cancellation_event_id", "cancellation_date", "coverage_start", "coverage_end", "refund_beneficiary_party_id" ], "properties": { "policy_id": { "type": "string", "description": "Identifier of the policy being cancelled.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "description": "Identifier of the product whose ruleset binding governs refund method/config.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cancellation_event_id": { "type": "string", "description": "Stable identifier of the cancellation event being settled.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "cancellation_date": { "type": "string", "format": "date-time", "description": "RFC3339 cancellation effective timestamp; resolves the as-was ruleset binding (governed contract)." }, "coverage_start": { "type": "string", "format": "date-time", "description": "RFC3339 start of the coverage period the refund applies to." }, "coverage_end": { "type": "string", "format": "date-time", "description": "RFC3339 end of the coverage period the refund applies to." }, "refund_beneficiary_party_id": { "type": "string", "description": "Party that the refund is owed to. Recorded on the credit leg.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "examples": { "pro_rata": { "summary": "Pro-rata refund example", "value": { "data": { "type": "premium-cancellation-refunds", "attributes": { "policy_id": "pol-001", "product_id": "prod-001", "cancellation_event_id": "evt-001", "cancellation_date": "2026-04-01T00:00:00Z", "coverage_start": "2026-01-01T00:00:00Z", "coverage_end": "2027-01-01T00:00:00Z", "refund_beneficiary_party_id": "party-001" } } } } } } } }, "responses": { "200": { "description": "Idempotent replay; original transaction returned with `is_replay=true` and no new rows.", "headers": { "Content-Type": { "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } }, "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "premium-cancellation-refunds" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "transaction_id", "is_replay", "ledger_entry_ids", "explanation_tree_id" ], "properties": { "transaction_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "is_replay": { "type": "boolean", "enum": [ true ] }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" } }, "explanation_tree_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "refund_amount": { "type": "integer", "format": "int64", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "201": { "description": "Refund evaluated. Non-zero refunds create a balanced premium_refund transaction; zero-refund outcomes persist explanation only.", "headers": { "Content-Type": { "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } }, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-cancellation-refunds" ] }, "id": { "type": "string", "description": "Ledger transaction_id of the posted refund; empty for zero-refund explanation-only outcomes.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "transaction_id", "is_replay", "ledger_entry_ids", "explanation_tree_id" ], "properties": { "transaction_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "is_replay": { "type": "boolean", "enum": [ false ] }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 2, "description": "Ordered debit-first, then credit for non-zero refunds; empty for zero-refund explanation-only outcomes." }, "explanation_tree_id": { "type": "string", "description": "ID of the persisted AC-7 explanation tree (governed contract); same value stamped on both ledger legs.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "refund_amount": { "type": "integer", "format": "int64", "description": "Refund amount in minor units (governed contract).", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "method": { "type": "string", "enum": [ "pro_rata", "short_rate", "minimum_earned" ] }, "calculation": { "$ref": "#/components/schemas/CalculationAttributes" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Malformed request (bad RFC3339 dates, malformed JSON body).", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing or invalid actor context (governed contract `UNAUTHORIZED`)." }, "415": { "description": "Unsupported media type \u2014 request must be `application/vnd.api+json`.\nEnvelope `errors[].code = UNSUPPORTED_MEDIA_TYPE`.\n" }, "422": { "description": "Validation failure. Stable error codes (envelope `errors[].code`).\nConfig-shape codes follow the contract canonical error table; no generic\n`REFUND_CONFIG_INVALID` / `REFUND_CONFIG_NOT_FOUND_AS_OF` is returned\non the refund-config path.\n- `IDEMPOTENCY_KEY_REQUIRED` \u2014 missing or empty `Idempotency-Key` header.\n- `REFUND_BENEFICIARY_REQUIRED` \u2014 `refund_beneficiary_party_id` missing.\n- `CANCELLATION_EVENT_REQUIRED` \u2014 `cancellation_event_id` missing.\n- `BINDING_NOT_FOUND_AS_OF` \u2014 no as-was ruleset binding at `cancellation_date`,\n or no `ruleset_version` for the binding (the provider collapses both\n cases to this canonical code).\n- `REFUND_METHOD_REQUIRED` \u2014 `cancellation_refund.method` missing in the ruleset snapshot.\n- `REFUND_METHOD_UNSUPPORTED` \u2014 method is not one of\n `pro_rata` / `short_rate` / `minimum_earned`.\n- `ROUNDING_MODE_REQUIRED` \u2014 `cancellation_refund.rounding_mode` missing.\n- `ROUNDING_MODE_UNSUPPORTED` \u2014 rounding mode is not `floor_minor_unit`.\n- `DAY_COUNT_CONVENTION_REQUIRED` \u2014 pro-rata method has no `day_count_convention`.\n- `DAY_COUNT_CONVENTION_UNSUPPORTED` \u2014 convention is not\n `actual/365` / `actual/360` / `30/360` / `actual/actual`.\n- `SHORT_RATE_TABLE_REQUIRED` \u2014 short-rate method has no\n `cancellation_refund.short_rate_table` or no `short_rate_table.version`.\n- `SHORT_RATE_TABLE_INVALID` \u2014 a `short_rate_table.rows[]` entry has\n fractional / non-integer / out-of-range (`earned_pct_bps` \u2209 `[0, 10000]`)\n values. Integer fields are decoded via `json.Number` and reject\n `float64` outright (governed contract).\n- `SHORT_RATE_ROW_NOT_FOUND` \u2014 no row matches the elapsed months at\n cancellation (raised by the calculator, not the provider).\n- `MINIMUM_EARNED_AMOUNT_REQUIRED` \u2014 minimum-earned method has no\n `cancellation_refund.minimum_earned_amount_minor`.\n- `MINIMUM_EARNED_AMOUNT_INVALID` \u2014 minimum-earned amount is negative,\n fractional, or not an int64.\n- `POLICY_DATES_INVALID` \u2014 coverage / cancellation dates incoherent.\n- `CURRENCY_REQUIRED`, `PAID_AMOUNT_REQUIRED` \u2014 calculator inputs missing.\n- `LEDGER_CATEGORY_INVALID` \u2014 entry produced with wrong `entry_category` (governed contract).\n- `LEDGER_POSTING_UNBALANCED` \u2014 debit total \u2260 credit total (defensive).\n- `REFUND_CONFIG_BINDING_REQUIRED` \u2014 defensive: provider called with nil binding.\n- `TENANT_CONTEXT_INVALID` \u2014 `X-Tenant-Context` is missing, malformed, or not authorized for tree storage.\n", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "503": { "description": "Service unavailable \u2014 cancellation refund service is not configured." } }, "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": "mixed", "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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}/allocation": { "get": { "operationId": "getPremiumAllocation", "summary": "Get allocation snapshot for a premium", "description": "Returns the benefit-level allocation breakdown for a premium at a point in time.\nUses half-open temporal semantics under the governed contract.\n\nEach allocation row includes benefit_id, amount (Money object with amount_minor + currency_code), allocation_percentage_bps,\nallocation_basis, calculation_version, and allocation_rule_id (when basis is rule_based).\n", "tags": [ "Premium" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Premium identifier" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Point-in-time for temporal query (RFC3339). Defaults to now." } ], "responses": { "200": { "description": "Allocation snapshot retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-allocation-snapshots" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "premium_id", "benefit_id", "amount", "allocation_percentage_bps", "allocation_basis", "calculation_version", "effective_from" ], "properties": { "premium_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Allocated amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "allocation_percentage_bps": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000 }, "allocation_basis": { "type": "string", "enum": [ "bottom_up", "fixed", "rule_based" ] }, "calculation_version": { "type": "string" }, "allocation_rule_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "trigger": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request (malformed as_of timestamp)", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "404": { "description": "No allocation snapshot found for this premium", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes": { "post": { "tags": [ "Policy" ], "summary": "Create a new quote", "description": "Creates a persisted premium calculation (quote) with a 30-minute TTL.\nExactly one of pricing_snapshot_id, products, or product_id must be provided.\n", "operationId": "createQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" } } } }, "responses": { "201": { "description": "Quote created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": { "age": 35, "vehicle_value": 25000 }, "covers_selected": [ "COMP", "TPL" ], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 42, "trace_id": "trace-abc123" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Actor attribution missing or invalid. Code: ACTOR_ATTRIBUTION_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Semantic validation failure. Codes: PRICING_INPUT_REQUIRED,\nPRICING_INPUT_CONFLICT, EFFECTIVE_DATE_INVALID, EXPIRY_DATE_INVALID,\nSUPERSEDES_QUOTE_NOT_FOUND, TENANT_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "PRICING_INPUT_REQUIRED", "title": "Validation Error", "detail": "Exactly one of pricing_snapshot_id, products, or product_id must be provided" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "tags": [ "Policy" ], "summary": "List quotes by comparison reference", "description": "Returns all quotes for a given comparison_ref, ordered by created_at DESC.\nTenant-scoped to prevent cross-tenant leakage.\n", "operationId": "listQuotesByComparisonRef", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "comparison_ref", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comparison reference to filter quotes" } ], "responses": { "200": { "description": "Quotes matching the comparison reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteListResponse" }, "example": { "status": "success", "data": [ { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc", "comparison_ref": "cmp-xyz789" } ], "telemetry": { "total_ms": 18, "trace_id": "trace-def456" } } } } }, "422": { "description": "Missing comparison_ref (COMPARISON_REF_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "bounded-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "bounded-list", "request_parameters": [], "consumer_posture": "explicit-bounded-list", "exception": "This list is intentionally published as an API 0.1.45 bounded-list exception with no page traversal contract. Consumers must not infer cursor, offset, or full-history traversal semantics from this operation.", "response_metadata": [ "meta.total" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "comparison_ref" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}": { "get": { "tags": [ "Policy" ], "summary": "Retrieve a quote by ID", "description": "Returns the persisted quote if active. Returns 404 for unknown IDs\n(including cross-tenant lookups) and 410 Gone for expired quotes.\n", "operationId": "getQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Active quote retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 12, "trace_id": "trace-ghi789" } } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "QUOTE_NOT_FOUND", "title": "Not Found", "detail": "Quote not found or belongs to a different tenant" } ] } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "410", "code": "QUOTE_EXPIRED", "title": "Gone", "detail": "Quote has expired (valid_until exceeded)" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/approve": { "post": { "tags": [ "Policy" ], "summary": "Approve a quote (indicative to firm)", "description": "Transitions a quote from indicative to firm status.\nRequires actor attribution (governed contract).\n", "operationId": "approveQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Quote approved (status changed to firm)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 15, "trace_id": "trace-jkl012" } } } } }, "401": { "description": "Actor attribution missing or invalid (ACTOR_ATTRIBUTION_REQUIRED).\n was 422 prior to this change.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid transition (INVALID_QUOTE_TRANSITION) or\nmissing tenant (TENANT_REQUIRED).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/decline": { "post": { "tags": [ "Policy" ], "summary": "Decline a quote", "description": "Transitions a quote to declined status. Requires a reason_code.\nRequires actor attribution (governed contract).\n", "operationId": "declineQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineQuoteRequest" } } } }, "responses": { "200": { "description": "Quote declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, "telemetry": { "total_ms": 11, "trace_id": "trace-mno345" } } } } }, "401": { "description": "Actor attribution missing or invalid (ACTOR_ATTRIBUTION_REQUIRED).\n was 422 prior to this change.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Missing reason_code (DECLINE_REASON_REQUIRED),\ninvalid transition (INVALID_QUOTE_TRANSITION), or\nmissing tenant (TENANT_REQUIRED).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/bind": { "post": { "tags": [ "Policy" ], "summary": "Bind a firm quote to create a policy", "description": "Binds a firm quote, creating a policy, premium allocation, ledger entries,\nand explanation tree. Only firm quotes can be bound.\nRequires actor attribution (governed contract).\n", "operationId": "bindQuote", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Idempotency key for bind operations (required under the governed contract)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindQuoteRequest" } } } }, "responses": { "201": { "description": "Quote bound successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindQuoteResultResponse" }, "example": { "status": "success", "data": { "quote_id": "qte-a1b2c3d4", "policy_id": "pol-xyz789", "premium_ids": [ "prm-abc001" ], "allocation_explanation_tree_id": "tree-001", "ledger_entry_ids": [ "led-001", "led-002" ] }, "telemetry": { "total_ms": 340, "trace_id": "trace-pqr678" } } } } }, "400": { "description": "Missing required input. Codes: IDEMPOTENCY_KEY_REQUIRED, INVALID_REQUEST.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "IDEMPOTENCY_KEY_REQUIRED", "title": "Bad Request", "detail": "Idempotency-Key header is required for bind operations" } ] } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "QUOTE_NOT_FOUND", "title": "Not Found", "detail": "Quote not found or belongs to a different tenant" } ] } } } }, "409": { "description": "Quote already bound (QUOTE_ALREADY_BOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "QUOTE_ALREADY_BOUND", "title": "Conflict", "detail": "Quote has already been bound to a policy" } ] } } } }, "410": { "description": "Quote has expired (QUOTE_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "410", "code": "QUOTE_EXPIRED", "title": "Gone", "detail": "Quote has expired (valid_until exceeded)" } ] } } } }, "412": { "description": "Quote not in firm status (QUOTE_NOT_FIRM)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "412", "code": "QUOTE_NOT_FIRM", "title": "Precondition Failed", "detail": "Quote must be in firm status to bind" } ] } } } }, "422": { "description": "Validation failure. Codes: QUOTE_SNAPSHOT_INVALID,\nPREMIUM_DRIFT_EXCEEDED, LEDGER_IMBALANCED,\nQUOTE_PARTY_MISMATCH_REQUOTE_REQUIRED,\nSUPERSEDES_QUOTE_NOT_FOUND, TENANT_REQUIRED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "QUOTE_SNAPSHOT_INVALID", "title": "Validation Error", "detail": "Quote pricing snapshot is no longer valid" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/quotes/{id}/chain": { "get": { "tags": [ "Policy" ], "summary": "Get quote supersession chain", "description": "Returns the full supersession chain for a quote, ordered oldest-first.\nWalks backward through supersedes_quote_id links and reverses.\n", "operationId": "getQuoteChain", "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Quote identifier" } ], "responses": { "200": { "description": "Supersession chain (oldest-first)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteListResponse" }, "example": { "status": "success", "data": [ { "quote_id": "qte-earlier", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-09T10:00:00Z", "valid_until": "2026-06-09T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc" }, { "quote_id": "qte-a1b2c3d4", "product_id": "prod-abc123", "effective_date": "2026-04-01T00:00:00Z", "expiry_date": "2027-04-01T00:00:00Z", "underwriting_data": {}, "covers_selected": [], "pricing_snapshot": {}, "created_at": "2026-06-10T10:00:00Z", "valid_until": "2026-06-10T10:30:00Z", "actor_type": "human", "actor_id": "usr-abc", "actor_original_id": "usr-abc", "supersedes_quote_id": "qte-earlier" } ], "telemetry": { "total_ms": 9, "trace_id": "trace-stu901" } } } } }, "404": { "description": "Quote not found (QUOTE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/payments": { "get": { "operationId": "listPayments", "summary": "List payments", "description": "Retrieves a cursor-paginated list of payments for the current tenant.\n\nResults are sorted by created_at descending with id as a stable\ntie-breaker.\n\nUse `page[size]` and `page[after]` for pagination. Legacy `limit` and\n`offset` query parameters are rejected.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentListResponse" }, "example": { "data": [ { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "completed", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "reference_id": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "reference_type": "premium", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-01T08:30:00Z", "processed_at": "2026-04-01T08:30:00Z" }, { "id": "b02b9190-8861-571a-9c77-e5ca374c70b7", "amount": { "amount_minor": 340000, "currency_code": "gbp" }, "status": "pending", "payment_method": "bank_transfer", "description": "Quarterly premium \u2014 property all-risks POL-2026-00456", "reference_id": "aa2bc3a2-2c63-5c9f-bd68-6f1c49d6ba59", "reference_type": "premium", "created_at": "2026-04-02T09:15:00Z", "updated_at": "2026-04-02T09:15:00Z", "processed_at": null } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMlQwOToxNTowMFoiLCJpZCI6ImM5ZDBlMWYyLWEzYjQtNTY3OC1jZGVmLTc4OTAxMjM0NTY3OCJ9" }, "status": "success", "message": "Payments retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Creates a new payment record in `pending` status.\n\nThe payment is not processed immediately. Use the\n`POST /v1/payments/{id}/process` endpoint to initiate processing.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "example": { "amount": { "amount_minor": 275000, "currency_code": "kes" }, "payment_method": "bank_transfer", "description": "Annual premium \u2014 liability professional indemnity POL-2026-00789", "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7", "reference_type": "premium", "party_id": "07805e66-69d7-5b42-a978-32729404b560", "metadata": { "source": "broker-portal", "broker_id": "BRK-0087" } } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "1724e0cd-6c5f-5bc3-a252-3e03f4c4a43b", "amount": { "amount_minor": 275000, "currency_code": "kes" }, "status": "pending", "payment_method": "bank_transfer", "description": "Annual premium \u2014 liability professional indemnity POL-2026-00789", "reference_id": "698cb660-df66-5b55-ba57-6fc65c6a27f7", "reference_type": "premium", "party_id": "07805e66-69d7-5b42-a978-32729404b560", "metadata": { "source": "broker-portal", "broker_id": "BRK-0087" }, "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T10:00:00Z", "processed_at": null }, "status": "success", "message": "Payment created successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get a payment by ID", "description": "Retrieves a single payment by its unique identifier.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updatePayment", "summary": "Update a payment", "description": "Updates a payment record. Only payments in `pending` status can be updated.\n\nFields that can be updated: amount, currency, payment_method, description,\nreference_id, reference_type, metadata.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Updated payment amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Updated human-readable description", "example": "Adjusted monthly premium \u2014 motor comprehensive policy POL-2026-00123" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Updated reference to associated resource", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Updated type of referenced resource" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated extensible metadata" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Payment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}/process": { "post": { "operationId": "processPayment", "summary": "Process a payment", "description": "Initiates processing for a pending payment.\n\nTransitions the payment through the lifecycle:\n`pending` -> `processing` -> `completed` (or `failed`).\n\nThis is an asynchronous operation. The response confirms the payment\nhas been submitted for processing. Poll the payment status or use\nwebhooks to track completion.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment submitted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "processing", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-01T08:30:00Z", "processed_at": null }, "status": "success", "message": "Payment submitted for processing" } } } }, "400": { "description": "Bad request or payment is not in a processable state (INVALID_REQUEST)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Bad Request", "detail": "Payment is in 'completed' status and cannot be processed again" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payments/{id}/cancel": { "post": { "operationId": "cancelPayment", "summary": "Cancel a payment", "description": "Cancels a payment. Only payments in `pending` or `processing` status\ncan be cancelled.\n\nTransitions the payment to `cancelled` status. This action cannot be undone.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "amount": { "amount_minor": 125000, "currency_code": "usd" }, "status": "cancelled", "payment_method": "debit_order", "description": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123", "created_at": "2026-04-01T06:00:00Z", "updated_at": "2026-04-03T11:00:00Z", "processed_at": null }, "status": "success", "message": "Payment cancelled successfully" } } } }, "400": { "description": "Bad request or payment is not in a cancellable state (INVALID_REQUEST)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Bad Request", "detail": "Payment is in 'completed' status and cannot be cancelled" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules": { "get": { "operationId": "listPaymentSchedules", "summary": "List payment schedules", "description": "Retrieves a cursor-paginated list of payment schedules for the current\ntenant.\n\nResults are derived from aggregate Premium rows and sorted by\neffective_date descending with id as a stable tie-breaker.\n\nPayment schedules define recurring cadence obligations tied to policies\n(e.g. monthly debit orders for motor premiums, quarterly bank transfers\nfor property cover). The list surface reports cadence definitions; per-\ninstalment paid/overdue state belongs to the payment settlement surface.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of payment schedules to return in this page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page.\nDo not construct or modify this value.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payment schedules retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentScheduleListResponse" }, "example": { "data": [ { "id": "24161ecd-8592-537c-849c-575aea8b40f1", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "frequency": "monthly", "amount": { "amount_minor": 125000, "currency_code": "zar" }, "status": "active", "next_due_date": "2026-05-01", "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-04-01T08:30:00Z" }, { "id": "002b084a-12bc-5d94-b2d6-40622d47fb4c", "policy_id": "pol_01h9xg2c7e8f4a5b6c7d8e9f0b", "frequency": "quarterly", "amount": { "amount_minor": 850000, "currency_code": "zar" }, "status": "active", "next_due_date": "2026-07-01", "created_at": "2026-02-01T12:00:00Z", "updated_at": "2026-04-01T12:00:00Z" } ], "meta": { "page_size": 20, "has_more": true, "next_cursor": "eyJlZmZlY3RpdmVfZGF0ZSI6IjIwMjYtMDItMDFUMDA6MDA6MDBaIiwiaWQiOiJhMmIzYzRkNS1lNmY3LTg5MDEtYmNkZS05MDEyMzQ1Njc4OTAifQ==" }, "status": "success", "message": "Payment schedules retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "post": { "operationId": "createPaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule creation workflow is implemented.", "source": "runtime source" }, "summary": "Create a payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule creation workflow is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "policy_id", "frequency", "amount", "currency", "next_due_date" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy this schedule services", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "frequency": { "$ref": "#/components/schemas/PaymentFrequency" }, "amount": { "type": "integer", "format": "int64", "description": "Scheduled payment amount per period in the smallest currency unit (e.g. cents). Exact integer representation.", "minimum": 0, "example": 420000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "example": "EUR" }, "next_due_date": { "type": "string", "format": "date", "description": "First scheduled payment date", "example": "2026-06-01" } }, "additionalProperties": false }, "example": { "policy_id": "41866ac2-9965-5dac-b793-aabd56eadcbd", "frequency": "half_yearly", "amount": 420000, "currency": "EUR", "next_due_date": "2026-06-01" } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule creation is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Payment schedule mutation/detail workflow is not implemented; list is the only supported payment-schedule surface." } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}": { "get": { "operationId": "getPaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule detail workflow is implemented.", "source": "runtime source" }, "summary": "Get a payment schedule by ID", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule detail workflow is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule detail retrieval is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Payment schedule mutation/detail workflow is not implemented; list is the only supported payment-schedule surface." } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}/pause": { "post": { "operationId": "pausePaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule state machine is implemented.", "source": "runtime source" }, "summary": "Pause a payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule state machine is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule pause is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Payment schedule mutation/detail workflow is not implemented; list is the only supported payment-schedule surface." } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/payment-schedules/{id}/resume": { "post": { "operationId": "resumePaymentSchedule", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime handler returns 501 until the payment-schedule state machine is implemented.", "source": "runtime source" }, "summary": "Resume a paused payment schedule", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until the payment-schedule state machine is implemented.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Payment schedule UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Payment schedule resume is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Payment schedule mutation/detail workflow is not implemented; list is the only supported payment-schedule surface." } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices with cursor pagination", "description": "Retrieves a paginated list of invoices for the current tenant using\ncursor-based pagination under the governed contract.\n\nLegacy offset-based pagination (limit/offset query params) is rejected\nwith 400 LEGACY_PAGINATION.\n\nResults sorted by created_at descending.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 25, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Cursor for the next page (invoice ID from previous response)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoices retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "400": { "description": "Bad request. Codes: MISSING_TENANT, LEGACY_PAGINATION,\nINVALID_PAGE_SIZE, PAGE_SIZE_EXCEEDED.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "legacy_pagination": { "summary": "Legacy pagination rejected", "value": { "errors": [ { "status": "400", "code": "LEGACY_PAGINATION", "title": "Legacy Pagination Not Supported", "detail": "Use page[size] and page[after] for cursor-based pagination under the governed contract" } ] } }, "invalid_page_size": { "summary": "Invalid page size", "value": { "errors": [ { "status": "400", "code": "INVALID_PAGE_SIZE", "title": "Invalid Page Size", "detail": "page[size] must be a positive integer" } ] } }, "page_size_exceeded": { "summary": "Page size exceeds maximum", "value": { "errors": [ { "status": "400", "code": "PAGE_SIZE_EXCEEDED", "title": "Page Size Exceeded", "detail": "page[size] must not exceed 100" } ] } } } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get a single invoice by ID", "description": "Retrieves a single invoice by its unique identifier.\nReturns 404 for unknown IDs or cross-tenant access attempts.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "id", "in": "path", "required": true, "description": "Invoice identifier", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing tenant header (MISSING_TENANT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } } } }, "404": { "description": "Invoice not found (INVOICE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "INVOICE_NOT_FOUND", "title": "Invoice Not Found", "detail": "The requested invoice does not exist or belongs to another tenant" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/invoices/{id}/finalize": { "post": { "operationId": "finalizeInvoice", "summary": "Finalize an invoice", "description": "Finalizes a draft invoice, making it immutable.\nRequires actor attribution headers under the governed contract.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-ID", "in": "header", "required": true, "description": "Actor identifier (governed contract)", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-Type", "in": "header", "required": true, "description": "Actor type (governed contract)", "schema": { "type": "string", "enum": [ "human", "service", "agent" ] } }, { "name": "id", "in": "path", "required": true, "description": "Invoice identifier", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "200": { "description": "Invoice finalized successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing required header. Codes: MISSING_TENANT,\nMISSING_ACTOR_ID, MISSING_ACTOR_TYPE.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "missing_actor_id": { "summary": "Missing actor ID header", "value": { "errors": [ { "status": "400", "code": "MISSING_ACTOR_ID", "title": "Missing Actor ID", "detail": "X-Actor-ID header is required for mutation endpoints" } ] } }, "missing_actor_type": { "summary": "Missing actor type header", "value": { "errors": [ { "status": "400", "code": "MISSING_ACTOR_TYPE", "title": "Missing Actor Type", "detail": "X-Actor-Type header is required for mutation endpoints" } ] } } } } } }, "404": { "description": "Invoice not found (INVOICE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "INVOICE_NOT_FOUND", "title": "Invoice Not Found", "detail": "The requested invoice does not exist or belongs to another tenant" } ] } } } }, "409": { "description": "Invoice already finalized (INVOICE_CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "INVOICE_CONFLICT", "title": "Invoice Conflict", "detail": "Invoice has already been finalized and cannot be modified" } ] } } } }, "422": { "description": "Invalid invoice state (INVALID_INVOICE_STATE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_INVOICE_STATE", "title": "Invalid Invoice State", "detail": "Invoice is not in a state that allows finalization" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/billing/cycles/close": { "post": { "operationId": "closeBillingCycle", "summary": "Close a billing cycle", "description": "Closes a billing cycle for the specified period, generating an invoice.\nRequires actor attribution headers under the governed contract.\n", "tags": [ "Payment" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-ID", "in": "header", "required": true, "description": "Actor identifier (governed contract)", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "name": "X-Actor-Type", "in": "header", "required": true, "description": "Actor type (governed contract)", "schema": { "type": "string", "enum": [ "human", "service", "agent" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period_start", "period_end" ], "properties": { "period_start": { "type": "string", "format": "date-time", "description": "Start of the billing period (RFC3339)", "example": "2026-03-01T00:00:00Z" }, "period_end": { "type": "string", "format": "date-time", "description": "End of the billing period (RFC3339)", "example": "2026-03-31T23:59:59Z" }, "idempotency_key": { "type": "string", "description": "Optional idempotency key for deduplication" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Billing cycle closed and invoice created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "Missing required header or invalid request body.\nCodes: MISSING_TENANT, MISSING_ACTOR_ID, MISSING_ACTOR_TYPE, INVALID_REQUEST.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_tenant": { "summary": "Missing tenant header", "value": { "errors": [ { "status": "400", "code": "MISSING_TENANT", "title": "Missing Tenant", "detail": "X-Tenant-Context header is required" } ] } }, "invalid_request": { "summary": "Invalid request body", "value": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Invalid Request", "detail": "Request body must include period_start and period_end in RFC3339 format" } ] } } } } } }, "409": { "description": "Invoice immutable conflict (INVOICE_IMMUTABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "INVOICE_IMMUTABLE", "title": "Billing Error", "detail": "Invoice for this period has already been finalized" } ] } } } }, "422": { "description": "Invalid cycle window (INVALID_CYCLE_WINDOW)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "INVALID_CYCLE_WINDOW", "title": "Invalid Cycle Window", "detail": "period_end must be after period_start" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/accounts/{code}/balance": { "get": { "operationId": "getAccountBalance", "summary": "Get account balance", "description": "Computes and returns the balance for a specific ledger account.\n\nSupports point-in-time queries via the `as_of` parameter for\nhistorical balance lookups (as-was semantics per platform principle).\n\nThe response includes an explanation tree documenting the inputs,\nrule version, and computation method used.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "code", "in": "path", "required": true, "description": "Account code to query (e.g. PREM-RCV-001, CLM-PAY-001)", "schema": { "type": "string", "example": "PREM-RCV-001" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time for the balance computation (ISO 8601).\nIf omitted, returns the current balance.\n", "schema": { "type": "string", "format": "date-time", "example": "2026-03-31T23:59:59Z" } } ], "responses": { "200": { "description": "Account balance computed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResultResponse" }, "example": { "data": { "account_code": "PREM-RCV-001", "as_of": "2026-03-31T23:59:59Z", "currency": "USD", "amount": 4525075, "entry_count": 128, "explanation": { "inputs": { "account_code": "PREM-RCV-001", "date_from": "2026-01-01T00:00:00Z", "date_to": "2026-03-31T23:59:59Z", "include_pending": false }, "rule_version": "balance-calc-v2.1.0", "computation": "Sum of posted credits minus posted debits for account PREM-RCV-001", "entry_ids": [ "50447be1-27bd-5a7a-b51c-edce72303e3f", "ba8f3ab8-3beb-55dc-874f-040a4f50529a" ] } }, "status": "success", "message": "Account balance computed successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries/{entry_id}/reversals": { "post": { "operationId": "createReversal", "summary": "Create a ledger entry reversal", "description": "Creates a reversing entry for a previously posted ledger entry.\nThe original entry's status transitions to `reversed`, and a new\nentry with the opposite entry_type and same amount is created.\n\nThis preserves the full audit trail rather than modifying or\ndeleting the original entry (platform principle explainability).\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "entry_id", "in": "path", "required": true, "description": "Ledger entry UUID to reverse", "schema": { "type": "string", "format": "uuid", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason", "posted_by" ], "properties": { "reason": { "type": "string", "description": "Reason for the reversal (required for audit trail)", "example": "Incorrect account code \u2014 premium posted to claims payable in error" }, "posted_by": { "type": "string", "description": "User or service authorising the reversal", "example": "hello@axiom.express" }, "entry_date": { "type": "string", "format": "date-time", "description": "Accounting date for the reversal (defaults to now)", "example": "2026-04-01T00:00:00Z" } }, "additionalProperties": false }, "example": { "reason": "Incorrect account code \u2014 premium posted to claims payable in error", "posted_by": "hello@axiom.express", "entry_date": "2026-04-01T00:00:00Z" } } } }, "responses": { "201": { "description": "Reversal entry created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReversalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Entry has already been reversed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "409", "code": "STATE_CONFLICT", "title": "Conflict", "detail": "Ledger entry has already been reversed" } ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/integrity/verify": { "post": { "operationId": "verifyIntegrity", "summary": "Verify ledger integrity", "description": "Runs integrity checks on the ledger to detect anomalies such as\nunbalanced transactions, orphaned entries, or sequence gaps.\n\nThis is a read-only operation that does not modify any data.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_codes": { "type": "array", "items": { "type": "string" }, "description": "Restrict verification to specific accounts (all if omitted)", "example": [ "PREM-RCV-001" ] }, "date_from": { "type": "string", "format": "date-time", "description": "Start of verification period", "example": "2026-01-01T00:00:00Z" }, "date_to": { "type": "string", "format": "date-time", "description": "End of verification period", "example": "2026-03-31T23:59:59Z" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Integrity verification completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerIntegrityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries": { "get": { "operationId": "listLedgerEntries", "summary": "List ledger entries for the tenant", "description": "Returns the tenant's ledger entries (keyset-ordered by `entry_id`\nascending). Cursor-paginated under the governed contract: pass `page[size]`\nto bound the page and `page[after]` (an opaque cursor from a prior\nresponse's `meta.next_cursor`) to fetch the next page. Each entry is a\ndouble-entry posting line (governed contract); amounts are exact integer minor units.\n\nOptional `reference_id` filter narrows the list to the postings recorded\nagainst a single source reference (e.g. a claim, policy, premium, or\npayment id). Absent = all entries for the tenant. The filter composes with\nthe existing operating-tenant tenant-isolated scope; it never widens it.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Optional filter \u2014 return only entries posted against this source\nreference id (`reference_id`, e.g. a claim / policy / premium /\npayment id). Absent = all entries for the tenant.\n" }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of entries to return (cursor page size, governed contract)." }, { "name": "page[after]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a prior response's `meta.next_cursor`. Treat as\nopaque; do not construct or modify. Omit to fetch the first page.\n" } ], "responses": { "200": { "description": "Ledger entries for the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEntryListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "reference_id" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/ledger/entries/{entry_id}/corrections": { "get": { "operationId": "getCorrections", "summary": "Get corrections for a ledger entry", "description": "Retrieves the correction history for a specific ledger entry,\nincluding any reversals and re-postings.\n\nResults sorted by created_at descending.\n\nThis supports the full audit trail and explainability requirements. \u2014 every correction is traceable back to the original entry.\n", "tags": [ "Ledger" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "entry_id", "in": "path", "required": true, "description": "Original ledger entry UUID", "schema": { "type": "string", "format": "uuid", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Corrections retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCorrectionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets": { "post": { "operationId": "createRuleset", "summary": "Create a ruleset", "description": "Creates a new ruleset in `draft` status.\n\nRulesets are versioned containers of business rules that govern\ndomain rule lanes such as underwriting, pricing, claims assessment,\ndocument completeness, or discount composition. Rules are data. \u2014 explicit, versioned,\ndeterministic, and auditable.\n\nOptionally specify a `base_ruleset` code to inherit rules from\nan existing ruleset as a starting point.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRulesetRequest" }, "example": { "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" } } } } }, "responses": { "201": { "description": "Ruleset created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" }, "example": { "data": { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "status": "draft", "version": 1, "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" }, "rules": [], "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T10:00:00Z" }, "status": "success", "message": "Ruleset created successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listRulesets", "summary": "List rulesets", "description": "Retrieves a paginated list of rulesets for the current tenant.\n\nResults are sorted by `recorded_at` descending with the ruleset `id` as\na stable cursor tiebreaker. Legacy `limit` and `offset` query parameters\nare rejected; use `page[size]` and `page[after]`.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of items to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as `meta.next_cursor` from the previous page", "schema": { "type": "string", "example": "eyJyZWNvcmRlZF9hdCI6IjIwMjYtMDgtMTVUMTI6MDA6MDBaIiwiaWQiOiJiMWMyZDNlNC1mNWE2LTc4OTAtYmNkZS1mMTIzNDU2Nzg5MDEifQ" } } ], "responses": { "200": { "description": "List of rulesets retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetListResponse" }, "example": { "data": [ { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "motor-comprehensive-v1", "name": "Motor Vehicle Rating Rules", "entity_type": "pricing", "description": "Validation and pricing rules for comprehensive motor insurance", "status": "active", "version": 3, "attributes": { "jurisdiction": "US", "product_line": "motor" }, "rules": null, "created_at": "2026-01-10T08:00:00Z", "updated_at": "2026-03-01T14:30:00Z" }, { "id": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "code": "property-allrisks-gb-v1", "name": "UK Property All-Risks", "entity_type": "underwriting", "description": "Validation and underwriting rules for all-risks property cover in the UK", "status": "draft", "version": 1, "attributes": { "jurisdiction": "GB", "product_line": "property" }, "rules": null, "created_at": "2026-03-15T09:00:00Z", "updated_at": "2026-03-15T09:00:00Z" } ], "meta": { "page_size": 20, "has_more": false }, "status": "success", "message": "Rulesets retrieved successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}": { "get": { "operationId": "getRuleset", "summary": "Get a ruleset by ID", "description": "Retrieves a single ruleset by its unique identifier, including\nall associated business rules.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "200": { "description": "Ruleset retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "put": { "operationId": "updateRuleset", "summary": "Update a ruleset", "description": "Updates the metadata of a ruleset (name, description, attributes).\n\nOnly rulesets in `draft` status can be updated. Active or deprecated\nrulesets are immutable \u2014 create a new version instead.\n\nThis does not modify individual rules. Use the rule-level endpoints\nto add, update, or remove rules.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated human-readable name", "example": "Motor Vehicle Rating Rules (Updated)" }, "description": { "type": "string", "description": "Updated description", "example": "Validation, pricing, and eligibility rules for comprehensive motor insurance" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated metadata", "example": { "jurisdiction": "US", "product_line": "motor", "effective_from": "2026-04-01" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Ruleset updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/test": { "post": { "operationId": "testRuleset", "summary": "Test a ruleset against input facts", "description": "Evaluates the entire ruleset against the provided input facts\nand returns the evaluation results.\n\nThis is a dry-run \u2014 no state is modified. The response includes\na full explanation tree showing which rules fired, their inputs,\nintermediate results, and final decisions (platform principle explainability).\n\nThe ruleset must be active before this endpoint runs. Testing a draft\nruleset returns `409 RULESET_NOT_ACTIVE`; use `/test-rule` for isolated\nexpression checks while authoring.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facts" ], "properties": { "facts": { "type": "object", "additionalProperties": true, "description": "Input facts for rule evaluation. Structure depends on the\nruleset's entity_type and the rules defined within it.\n", "example": { "applicant": { "age": 32, "licence_years": 10, "claims_history": 0 }, "vehicle": { "make": "Toyota", "model": "Hilux", "year_of_manufacture": 2023, "value": 450000 }, "cover": { "type": "comprehensive", "sum_insured": 450000 } } } }, "additionalProperties": false }, "example": { "facts": { "applicant": { "age": 32, "licence_years": 10, "claims_history": 0 }, "vehicle": { "make": "Toyota", "model": "Hilux", "year_of_manufacture": 2023, "value": 450000 }, "cover": { "type": "comprehensive", "sum_insured": 450000 } } } } } }, "responses": { "200": { "description": "Ruleset evaluation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/test-rule": { "post": { "operationId": "testSingleRule", "summary": "Test a single rule within a ruleset", "description": "Evaluates a single rule expression against the provided input facts.\nUseful for iterative rule development and debugging before the rule is\nadded to a ruleset.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expression", "data" ], "properties": { "expression": { "type": "string", "description": "CEL expression to test.", "example": "applicant.age >= 18" }, "data": { "type": "object", "additionalProperties": true, "description": "Input facts for rule evaluation", "example": { "applicant": { "age": 17, "licence_years": 0 } } } }, "additionalProperties": false }, "example": { "expression": "applicant.age >= 18", "data": { "applicant": { "age": 17, "licence_years": 0 } } } } } }, "responses": { "200": { "description": "Single rule evaluation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleRuleEvaluationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/deploy": { "post": { "operationId": "deployRuleset", "summary": "Deploy a ruleset", "description": "Transitions a ruleset from `draft` to `active` status, making it\navailable for evaluation in live policy, claim, and premium workflows.\n\nThis increments the ruleset version number. The previous active\nversion (if any) is transitioned to `deprecated` and retained\nfor as-was auditability.\n\nThis operation cannot be undone \u2014 to roll back, deploy the\nprevious version's rules in a new ruleset.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "activated_by" ], "properties": { "activated_by": { "type": "string", "description": "Actor identifier recorded in the deployment audit trail.", "example": "underwriter-user-003" } }, "additionalProperties": false }, "example": { "activated_by": "underwriter-user-003" } } } }, "responses": { "200": { "description": "Ruleset deployed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetResponse" }, "example": { "data": { "id": "7ffab4d3-56e1-548b-a116-a577714722cd", "code": "health-gap-ng-v1", "name": "Nigeria Health Gap Cover", "entity_type": "pricing", "description": "Pricing rules for health gap cover in Nigeria", "status": "active", "version": 2, "attributes": { "jurisdiction": "NG", "product_line": "health", "effective_from": "2026-07-01" }, "created_at": "2026-04-03T10:00:00Z", "updated_at": "2026-04-03T11:00:00Z" }, "status": "success", "message": "Ruleset deployed successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/rules": { "post": { "operationId": "addRule", "summary": "Add a rule to a ruleset", "description": "Adds a new business rule to a ruleset. The ruleset must be in\n`draft` status.\n\nRules are defined as CEL (Common Expression Language) expressions\nthat must be deterministic and side-effect free.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBusinessRuleRequest" }, "example": { "code": "max-vehicle-age", "name": "Maximum Vehicle Age", "rule_type": "validation", "expression": "vehicle.year_of_manufacture >= 2011", "description": "Vehicle must be no more than 15 years old for comprehensive cover in the test year", "priority": 20, "attributes": { "risk_category": "vehicle_eligibility" } } } } }, "responses": { "201": { "description": "Rule added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/rulesets/{id}/rules/{ruleId}": { "put": { "operationId": "updateRule", "summary": "Update a rule within a ruleset", "description": "Updates an existing business rule within a ruleset. The ruleset\nmust be in `draft` status.\n\nUpdatable fields: name, expression, description, priority,\nstatus, attributes, conditions, actions.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } }, { "name": "ruleId", "in": "path", "required": true, "description": "Rule UUID identifier within the ruleset", "schema": { "type": "string", "format": "uuid", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated rule name", "example": "Maximum Vehicle Age (Extended)" }, "expression": { "type": "string", "description": "Updated CEL expression", "example": "vehicle.year_of_manufacture >= 2006" }, "description": { "type": "string", "nullable": true, "description": "Updated description", "example": "Vehicle must be no more than 20 years old for extended comprehensive cover" }, "priority": { "type": "integer", "description": "Updated execution priority", "example": 20 }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Updated rule status" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated metadata" }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" } }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Rule updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "delete": { "operationId": "deleteRule", "summary": "Delete a rule from a ruleset", "description": "Removes a rule from a ruleset. The ruleset must be in `draft` status.\n\nRules in active or deprecated rulesets cannot be deleted \u2014 deprecate\nthe rule instead to preserve the audit trail.\n", "tags": [ "Ruleset" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Ruleset UUID identifier", "schema": { "type": "string", "format": "uuid", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" } }, { "name": "ruleId", "in": "path", "required": true, "description": "Rule UUID identifier within the ruleset", "schema": { "type": "string", "format": "uuid", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe" } } ], "responses": { "200": { "description": "Rule deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesetDeleteRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence": { "post": { "operationId": "createEvidenceRecord", "summary": "Create an evidence record", "description": "Creates a new evidence record capturing a decision, evaluation, or\nstate transition for audit and compliance purposes.\n\nEvidence records are immutable once created. The `content_hash` (SHA-256)\nis computed server-side and enables tamper detection.\n\nSupports platform principle (Explainability) \u2014 every material decision emits a durable\nexplanation tree stored as evidence.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvidenceRecordRequest" }, "example": { "record_type": "rule_evaluation", "subject_type": "policy", "subject_id": "e316666f-e293-5ccc-81a8-8a12fe4094c5", "content": { "evaluation": "premium_calculation", "inputs": { "vehicle_value": 450000, "driver_age": 32, "claims_history": 0, "region": "New York" }, "rule_version": "motor-pricing-v2.0.1", "base_premium": 8100, "loadings": [], "discounts": [ { "type": "no_claims_bonus", "percentage": 0.2 } ], "final_premium": 6480 }, "created_by": "pricing-engine" } } } }, "responses": { "201": { "description": "Evidence record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvidenceRecordResponse" }, "example": { "status": "success", "data": { "id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "type": "evidence", "attributes": { "evidence_id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "content_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "canonicalization_version": "jcs-rfc8785-v1" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}": { "get": { "operationId": "getEvidenceRecord", "summary": "Get an evidence record by ID", "description": "Returns a single evidence record including its full content payload\nand integrity hash.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evidence_id", "in": "path", "required": true, "description": "Evidence record UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "c0e531a6-9deb-53a8-873b-9736a707f52b" } ], "responses": { "200": { "description": "Evidence record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceRecordResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/query": { "post": { "operationId": "queryEvidence", "summary": "Query evidence records", "description": "Searches evidence records using structured filters. Supports filtering\nby subject, record type, date range, and content attributes.\n\nPOST is used instead of GET to support complex query payloads\nthat exceed URL length limits.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_type": { "type": "string", "description": "Filter by subject type", "example": "claim" }, "subject_id": { "type": "string", "description": "Filter by subject identifier", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "record_type": { "type": "string", "description": "Filter by evidence record type", "example": "decision_trace" }, "from_date": { "type": "string", "format": "date-time", "description": "Filter records created on or after this timestamp", "example": "2026-03-01T00:00:00Z" }, "to_date": { "type": "string", "format": "date-time", "description": "Filter records created before this timestamp", "example": "2026-03-12T23:59:59Z" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of records to skip" } }, "additionalProperties": false }, "example": { "subject_type": "claim", "subject_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "record_type": "decision_trace", "from_date": "2026-03-01T00:00:00Z", "limit": 50 } } } }, "responses": { "200": { "description": "Matching evidence records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryEvidenceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}/integrity-verifications": { "post": { "operationId": "verifyEvidenceIntegrity", "summary": "Verify integrity of a single evidence record", "description": "Recomputes the content hash for the specified evidence record and\ncompares it against the stored hash. Returns a verification result\nindicating whether the record has been tampered with.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evidence_id", "in": "path", "required": true, "description": "Evidence record UUID to verify", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "c0e531a6-9deb-53a8-873b-9736a707f52b" } ], "responses": { "201": { "description": "Integrity verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityVerificationResponse" }, "example": { "status": "success", "data": { "id": "d030a083-6627-5d10-a1ec-de4b762f556b", "type": "integrity-verification", "attributes": { "verification_id": "d030a083-6627-5d10-a1ec-de4b762f556b", "expected_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "actual_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "verified", "verified_at": "2026-03-12T10:20:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/verify": { "post": { "operationId": "verifyEvidence", "summary": "Batch-verify evidence record integrity", "description": "Verifies the integrity of multiple evidence records in a single request.\nUseful for periodic compliance audits or spot checks.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evidence_ids" ], "properties": { "evidence_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of evidence record IDs to verify", "minItems": 1, "maxItems": 100 } }, "additionalProperties": false }, "example": { "evidence_ids": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "00548ee3-5ea2-5e09-8975-93b2e0fe033e" ] } } } }, "responses": { "200": { "description": "Batch verification results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEvidenceResponse" }, "example": { "status": "success", "data": [ { "record_id": "c0e531a6-9deb-53a8-873b-9736a707f52b", "content_hash": "3a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "VERIFIED" }, { "record_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "content_hash": "4a7bd3e2e2d5f90c1e9b3c8a4d6f7e8b9a0c1d2e3f4567890abcdef12345678", "status": "TAMPERED" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/assemble": { "post": { "operationId": "assembleEvidencePack", "summary": "Assemble an evidence pack", "description": "Assembles a collection of evidence records into a named pack.\nEvidence packs provide a complete audit trail for a decision or event,\nbundling all related records for compliance reporting and review.\n\nunder the governed contract, packs are assembled on demand from existing records\nand are themselves immutable once created.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssembleEvidencePackRequest" }, "example": { "name": "Claim CLM-2026-00142 \u2014 Marine Cargo Adjudication Evidence Pack", "record_ids": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237" ], "assembled_by": "compliance-reporting-service" } } } }, "responses": { "200": { "description": "Evidence pack assembled", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidencePackResource" } }, "additionalProperties": true } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/{pack_id}": { "get": { "operationId": "getEvidencePack", "summary": "Get an evidence pack by ID", "description": "Returns an evidence pack including all constituent evidence records.\n", "tags": [ "Evidence" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "pack_id", "in": "path", "required": true, "description": "Evidence pack UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "00548ee3-5ea2-5e09-8975-93b2e0fe033e" } ], "responses": { "200": { "description": "Evidence pack with records", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidencePackResource" } }, "additionalProperties": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/compliance/evaluations/{evaluation_id}/report": { "get": { "operationId": "getComplianceReport", "summary": "Get a compliance evaluation report", "description": "Returns a compliance report for a completed evaluation, including\nper-jurisdiction findings, pack metadata, and explanation tree reference.\n\nunder the governed contract: compliance_assertion is always false \u2014 reports are\nevidence-enabling, not compliance-asserting.\n", "tags": [ "Compliance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "evaluation_id", "in": "path", "required": true, "description": "Compliance evaluation UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "6b6487c1-bf44-5a61-ad58-caf256e207b6" } ], "responses": { "200": { "description": "Compliance evaluation report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceReportResponse" }, "example": { "data": { "evaluation_id": "6b6487c1-bf44-5a61-ad58-caf256e207b6", "generated_at": "2026-04-08T12:00:05Z", "compliance_assertion": false, "findings": [ { "jurisdiction_code": "ZA", "status": "pass", "evidence_references": [ "3af4d529-138b-545f-a71b-a5a04ba7e417" ], "missing_evidence": [] } ], "ruleset_metadata": [ { "pack_id": "7dba3076-6baa-5957-8f89-482edba4ea47", "pack_version": "1.0.0" } ], "explanation_tree_id": "f0a8077c-3895-5ef6-922c-e35461d34efd" }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/vendors": { "post": { "operationId": "createVendor", "summary": "Register a new vendor", "description": "Creates a vendor record for a third-party service provider.\n\nVendors represent external organisations that process, store, or access\ntenant data. Each vendor is tracked for compliance purposes (POPIA, GDPR)\nincluding data classification, security review status, and subprocessor chains.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorRequest" }, "example": { "data": { "type": "vendors", "attributes": { "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification for health insurance products", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "integrations": [ { "system_name": "MediCheck Claims API", "data_categories": [ "health_records" ], "data_direction": "ingress", "transfer_method": "rest_api" } ] } } } } } }, "responses": { "201": { "description": "Vendor created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" }, "example": { "data": { "type": "vendors", "attributes": { "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification for health insurance products", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "status": "draft", "integrations": [ { "integration_id": "ef3dae92-18c3-52d8-bb19-359e317362d6", "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "system_name": "MediCheck Claims API", "data_categories": [ "health_records" ], "data_direction": "ingress", "transfer_method": "rest_api" } ], "security_review_status": "pending", "security_review_approved_at": null, "created_at": "2026-03-12T10:00:00Z", "updated_at": "2026-03-12T10:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } }, "get": { "operationId": "listVendors", "summary": "List vendors", "description": "Returns a paginated list of vendor records for the tenant.\n\nSupports cursor-based pagination via `page[size]` and `page[after]` query parameters.\nResponse uses a JSON:API-style collection envelope with `data` array and `meta` object.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of vendors to return (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor for next page; obtained from previous response meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of vendors", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "meta": { "type": "object", "properties": { "page_size": { "type": "integer" }, "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": [ { "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "MediCheck Health Services", "purpose": "Medical underwriting and claims verification", "classification": "C", "accessed_data_classes": [ "health", "personal_identifiable" ], "status": "active", "created_at": "2026-02-01T09:00:00Z", "updated_at": "2026-03-05T16:20:00Z" }, { "vendor_id": "3164d499-6504-58ad-9020-f1f1377130f5", "name": "SafePay Financial Gateway", "purpose": "Premium collection and payment processing", "classification": "B", "accessed_data_classes": [ "financial", "personal_identifiable" ], "status": "active", "created_at": "2025-11-15T10:00:00Z", "updated_at": "2026-02-28T14:00:00Z" } ], "meta": { "page_size": 20, "next_cursor": "" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}": { "get": { "operationId": "getVendor", "summary": "Get a vendor by ID", "description": "Returns the full vendor record including integrations and subprocessors.\nResponse uses JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Vendor UUID identifier", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "responses": { "200": { "description": "Vendor record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } }, "patch": { "operationId": "updateVendor", "summary": "Update a vendor", "description": "Partially updates a vendor record. Only provided fields are modified.\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Vendor UUID identifier", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorRequest" }, "example": { "data": { "type": "vendors", "attributes": { "status": "active", "security_review_status": "approved" } } } } } }, "responses": { "200": { "description": "Vendor updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDataEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}/subprocessors": { "post": { "operationId": "createSubprocessor", "summary": "Add a subprocessor to a vendor", "description": "Registers a subprocessor under a vendor. Subprocessors are third parties\nthat the vendor engages to process data on behalf of the tenant.\n\nTracking subprocessors is required for POPIA and GDPR compliance, ensuring\nthe full data processing chain is documented and approved.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Parent vendor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubprocessorRequest" }, "example": { "data": { "type": "subprocessors", "attributes": { "name": "Azure US East", "service_scope": "Disaster recovery and backup storage for policy documents" } } } } } }, "responses": { "201": { "description": "Subprocessor created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubprocessorDataEnvelope" }, "example": { "data": { "type": "subprocessors", "attributes": { "subprocessor_id": "d3216bd6-21dd-572a-8396-9e1444af9bfb", "vendor_id": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "name": "Azure US East", "service_scope": "Disaster recovery and backup storage for policy documents", "approval_status": "pending", "approved_by": null, "approved_at": null, "change_reason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/vendors/{vendor_id}/subprocessors/{subprocessor_id}": { "patch": { "operationId": "updateSubprocessor", "summary": "Update a subprocessor", "description": "Partially updates a subprocessor record under a vendor.\nTypically used to change approval status or update service scope.\n\nRequest and response use JSON:API envelope format.\n", "tags": [ "Vendor" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "vendor_id", "in": "path", "required": true, "description": "Parent vendor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595" }, { "name": "subprocessor_id", "in": "path", "required": true, "description": "Subprocessor UUID", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "d3216bd6-21dd-572a-8396-9e1444af9bfb" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubprocessorRequest" }, "example": { "data": { "type": "subprocessors", "attributes": { "approval_status": "approved", "change_reason": "Annual subprocessor review completed \u2014 SOC 2 Type II report verified" } } } } } }, "responses": { "200": { "description": "Subprocessor updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubprocessorDataEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/balance": { "get": { "operationId": "getBenefitBalance", "summary": "Get benefit balance", "description": "Returns the current balance for a specific benefit type on a policy,\nshowing how much of the benefit limit has been consumed.\n\nSupports point-in-time queries via `as_of` and period-scoped queries\nvia `period_start`/`period_end` for benefits with annual or periodic\nlimits (e.g. annual dental limit, per-incident excess cap).\n\nunder the governed contract, benefit balances are computed from the ledger and\nare always consistent with claim payouts and adjustments.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefits for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier (e.g. hospitalisation, dental,\noptical, roadside_assistance, personal_accident).\n", "schema": { "type": "string" }, "example": "hospitalisation" }, { "name": "period_start", "in": "query", "required": false, "description": "Start of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "period_end", "in": "query", "required": false, "description": "End of the benefit period (ISO 8601 date)", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time query. Returns the benefit balance as it was\nat this timestamp. Defaults to current time if omitted.\n", "schema": { "type": "string", "format": "date-time" }, "example": "2026-03-12T00:00:00Z" } ], "responses": { "200": { "description": "Benefit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "balance", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit (decimal as string)", "example": "500000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount consumed (claimed and paid)", "example": "125000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "balance": { "type": "string", "description": "Remaining available balance", "example": "375000.00" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "period_start": { "type": "string", "format": "date", "description": "Start of the benefit period" }, "period_end": { "type": "string", "format": "date", "description": "End of the benefit period" }, "as_of": { "type": "string", "format": "date-time", "description": "Effective timestamp of the balance query" }, "claims_count": { "type": "integer", "description": "Number of claims consuming this benefit in the period" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "hospitalisation", "limit": "500000.00", "consumed": "125000.00", "balance": "375000.00", "currency": "USD", "period_start": "2026-01-01", "period_end": "2026-12-31", "as_of": "2026-03-12T00:00:00Z", "claims_count": 2 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type", "period_start", "period_end" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/available": { "get": { "operationId": "getBenefitAvailable", "summary": "Get available benefit amount", "description": "Returns the currently available (claimable) amount for a benefit type\non a policy, accounting for in-flight claims that have been filed\nbut not yet settled.\n\nThis differs from `/balance` in that it includes pending claims\nas reserved amounts, giving a more conservative view of availability\nsuitable for claim intake decisions.\n", "tags": [ "Benefit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "policy_id", "in": "query", "required": true, "description": "Policy UUID to query benefit availability for", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "example": "cc347178-b31f-571d-8ed1-b2513427d36f" }, { "name": "benefit_type", "in": "query", "required": true, "description": "Benefit type identifier", "schema": { "type": "string" }, "example": "dental" } ], "responses": { "200": { "description": "Available benefit amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "policy_id", "benefit_type", "limit", "consumed", "reserved", "available", "currency" ], "properties": { "policy_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "benefit_type": { "type": "string" }, "limit": { "type": "string", "description": "Total benefit limit", "example": "25000.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "consumed": { "type": "string", "description": "Amount from settled claims", "example": "8500.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "reserved": { "type": "string", "description": "Amount reserved by pending (in-flight) claims", "example": "3200.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "available": { "type": "string", "description": "Amount available for new claims\n(limit - consumed - reserved)\n", "example": "13300.00", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" }, "pending_claims": { "type": "integer", "description": "Number of in-flight claims reserving benefit", "example": 1 } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false }, "example": { "data": { "policy_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "benefit_type": "dental", "limit": "25000.00", "consumed": "8500.00", "reserved": "3200.00", "available": "13300.00", "currency": "USD", "pending_claims": 1 }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "benefit_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, { "description": "Implemented proration balance consumer. `reinsurance_balance` is an accepted fail-closed value until governed treaty authority exists.\n", "in": "query", "name": "consumer", "required": true, "schema": { "enum": [ "fund_balance", "earning_balance", "reinsurance_balance" ], "type": "string" } }, { "description": "Inclusive balance period start.", "in": "query", "name": "period_start", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive balance period end.", "in": "query", "name": "period_end", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Fund account code, required for fund_balance unless account_code is supplied.", "in": "query", "name": "fund_account_code", "required": false, "schema": { "type": "string" } }, { "description": "Generic account code for fund or earning balance scope.", "in": "query", "name": "account_code", "required": false, "schema": { "type": "string" } }, { "description": "Earning period key, required for earning_balance unless account_code is supplied.", "in": "query", "name": "earning_period_key", "required": false, "schema": { "type": "string" } }, { "description": "Include constituent proration component IDs and operation details.", "in": "query", "name": "decompose", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProrationBalanceResponse" } } }, "description": "Proration balance result." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [ "policies:read" ] } ], "summary": "Get Proration Balance", "tags": [ "Premium", "Policy", "Benefit" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "policy_id", "consumer", "period_start", "period_end", "fund_account_code", "account_code", "earning_period_key", "decompose" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "policies:read" ], "required_permissions": [ "policies:read" ], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation", "scope-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/dashboard": { "get": { "operationId": "getDashboardMetrics", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get dashboard metrics", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Dashboard analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/claims-by-status": { "get": { "operationId": "getClaimsByStatus", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get claims breakdown by status", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Claims-by-status analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/monthly-revenue": { "get": { "operationId": "getMonthlyRevenue", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get monthly revenue trend", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Monthly-revenue analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/analytics/top-products": { "get": { "operationId": "getTopProducts", "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime analytics handler returns 501 until tenant-owned analytics projections are implemented.", "source": "runtime source" }, "summary": "Get top products by premium volume", "description": "Published for route accountability in API 0.1.0. The runtime currently\nreturns 501 until tenant-owned analytics projections are implemented.\n", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Top-products analytics is not implemented in API 0.1.0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "501", "code": "NOT_IMPLEMENTED", "title": "Not Implemented", "detail": "Not implemented" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/reports/export": { "get": { "operationId": "exportReport", "summary": "Export a report", "description": "Generates and exports a report in the requested format (PDF or CSV).\n\nSupported report types:\n- `premium_collection` \u2014 Premium collection summary by product and period\n- `claims_register` \u2014 Claims register with status, amounts, and settlement details\n- `loss_ratio` \u2014 Loss ratio analysis by product line\n- `policy_register` \u2014 Policy register with coverage and premium details\n- `reconciliation` \u2014 Ledger reconciliation report\n- `commission_statement` \u2014 Broker commission statement\n\nThe response is the report file itself (binary content), not a\nJSON envelope.\n", "tags": [ "Report" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for tracing", "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, { "name": "type", "in": "query", "required": true, "description": "Report type to generate", "schema": { "type": "string", "enum": [ "premium_collection", "claims_register", "loss_ratio", "policy_register", "reconciliation", "commission_statement" ], "example": "premium_collection" } }, { "name": "format", "in": "query", "required": true, "description": "Output format for the report", "schema": { "type": "string", "enum": [ "pdf", "csv" ], "example": "pdf" } }, { "name": "date_from", "in": "query", "required": false, "description": "Start date for the report period (inclusive, ISO 8601 date)", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "required": false, "description": "End date for the report period (inclusive, ISO 8601 date)", "schema": { "type": "string", "format": "date", "example": "2026-03-31" } }, { "name": "product_code", "in": "query", "required": false, "description": "Filter report to a specific product code", "schema": { "type": "string", "example": "motor-comprehensive" } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary amounts (defaults to tenant base currency)", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } } ], "responses": { "200": { "description": "Report generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "PDF report binary content" } }, "text/csv": { "schema": { "type": "string", "description": "CSV report content" } } }, "headers": { "Content-Disposition": { "description": "Attachment filename for the downloaded report", "schema": { "type": "string", "example": "attachment; filename=\"premium-collection-2026-contract rule.pdf\"" } }, "Content-Length": { "description": "Size of the report file in bytes", "schema": { "type": "integer", "example": 245760 } } } }, "400": { "description": "Invalid report parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_REQUEST", "title": "Invalid request", "detail": "unknown report type \"unknown\". Accepted: dashboard, claims-by-status, monthly-revenue, top-products" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "type", "format", "date_from", "date_to", "product_code", "currency" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/inbox/messages": { "post": { "description": "Contract authority for POST /v1/inbox/messages (receiveInboxMessage) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "receiveInboxMessage", "parameters": [ { "description": "Operating-tenant context (binding: operating_tenant).", "in": "header", "name": "X-Tenant-Context", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (scope: tenant).", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } }, { "description": "Request correlation ID (governed contract). Generated by the server if omitted; always echoed in the response.", "in": "header", "name": "X-Correlation-ID", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "mailroom:inbox:read" ] } ], "summary": "Receive Inbox Message", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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": "nonstandard", "scopes": [ "mailroom:inbox:read" ], "required_permissions": [ "mailroom:inbox: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" ], "scope_exception": "One or more published scope names do not use the canonical resource:action form in API 0.1.45." }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 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/ingress/events": { "post": { "operationId": "ingestEvent", "summary": "Ingest an event", "description": "Receives an event into the Axiom ingress pipeline for asynchronous\nvalidation and processing.\n\nThis is an admitted alpha transport surface for asynchronous external\ninputs. It persists a durable inbox record and a tenant-scoped status\nrecord before returning 202 Accepted. `202 Accepted` means durable\nreceipt only. It does not mean the submitted event is valid, accepted\ninto the insurance domain, processed, or linked downstream.\n\nCallers must use the returned `status_url` or subscribe to a governed\nnotification channel when available. Polling the status endpoint is the\nauthoritative way to discover later validation and processing outcomes.\n\nIt is not a public self-service event catalogue, and event-type schemas\nare not yet published as a generated contract fragment. Event types,\npayload schemas, and promotion rules are tenant-owned configuration when\npromoted; they are not Axiom-owned public domain content.\n\n**Conditional availability:** This endpoint may return 404 if async\ningress is not enabled in the environment.\n\n**Response format:** JSON:API style \u2014 not the legacy wrapper.\n\n**Idempotency:** Events are deduplicated using `X-Webhook-Delivery-ID`\nwhen supplied. If the header is absent, the runtime derives a stable key\nfrom the source and request body bytes. Resubmitting the same key returns\nthe original `ingress_id`, current receipt status, and `status_url`.\n", "tags": [ "Ingress" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_type", "payload" ], "properties": { "event_type": { "type": "string", "description": "Tenant-owned external event type identifier. The public\ndeveloper-preview contract does not publish a stable event\ntype catalogue; use only values supplied in an issued tenant\nintegration runbook.\n", "example": "external.event.received" }, "source": { "type": "string", "description": "Optional source hint. The runtime may derive source from the\nauthenticated context or `X-Source` header.\n", "example": "external-ingress" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event actually occurred (as opposed to when it was\nreceived). If omitted, the server uses the receipt timestamp.\n", "example": "2026-03-12T09:30:00Z" }, "payload": { "type": "object", "additionalProperties": true, "description": "Tenant-owned boundary payload. Structure varies by event_type.\nNo public self-service payload schema catalogue is published\nin API 0.1.0. Treat payload shape as tenant-issued integration\nconfiguration, not Axiom-owned domain content.\n" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional event metadata (routing hints, trace context)" } }, "additionalProperties": false }, "examples": { "event_received": { "summary": "External event received", "value": { "event_type": "external.event.received", "source": "external-ingress", "occurred_at": "2026-03-12T09:30:00Z", "payload": { "external_reference": "event-2026-03-12-001", "occurred_at": "2026-03-12T09:30:00Z", "attributes": { "status": "received" } } } }, "event_with_metadata": { "summary": "External event with metadata", "value": { "event_type": "external.event.updated", "source": "external-ingress", "occurred_at": "2026-03-12T06:00:00Z", "payload": { "external_reference": "event-2026-03-12-002", "attributes": { "status": "updated" } }, "metadata": { "import_batch": "batch-2026-03-12" } } } } } } }, "responses": { "202": { "description": "Event submission durably received for asynchronous validation.\n\nThis response means receipt only. The caller must inspect\n`status_url` to determine whether validation later failed, the event\nbecame accepted for domain processing, or processing completed.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "ingress_id", "status_url", "correlation_id", "idempotency_key", "received_at" ], "properties": { "status": { "type": "string", "enum": [ "received" ], "description": "Initial mailroom status. Receipt has been persisted; domain acceptance has not yet been proven." }, "ingress_id": { "type": "string", "format": "uuid", "description": "Assigned ingress record identifier", "x-axiom-identifier-shape": "uuid" }, "status_url": { "type": "string", "description": "Relative URL for tenant-scoped polling of validation and processing state", "example": "/v1/ingress/events/491eb158-40d7-5094-9cf3-3e7a7b38fab6" }, "correlation_id": { "type": "string", "format": "uuid", "description": "Correlation ID for tracing this event through the pipeline", "x-axiom-identifier-shape": "uuid" }, "idempotency_key": { "type": "string", "description": "Echo of the supplied or runtime-derived idempotency key" }, "received_at": { "type": "string", "format": "date-time", "description": "Server-side receipt timestamp" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": { "status": "received", "ingress_id": "491eb158-40d7-5094-9cf3-3e7a7b38fab6", "status_url": "/v1/ingress/events/491eb158-40d7-5094-9cf3-3e7a7b38fab6", "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "idempotency_key": "external-ingress:event-2026-03-12-001", "received_at": "2026-03-12T09:30:05Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Async ingress is not enabled for the admitted environment.\nContact support to enable it.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "404", "code": "FEATURE_DISABLED", "title": "Not Found", "detail": "Event ingress is not enabled in this environment" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "published-429-response", "headers": [ "Retry-After", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" ], "numeric_commitment": "tenant-policy-runtime", "limit_source": "active tenant rate_limit_policies.limit", "window_source": "active tenant rate_limit_policies.window_secs", "enforcement": "gateway-rate-limit-runtime" } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/ingress/events/{ingress_id}": { "get": { "operationId": "getIngressEventStatus", "summary": "Get ingress event status", "description": "Returns the tenant-scoped status trail for an asynchronous event\nsubmission.\n\nUse this endpoint after `POST /v1/ingress/events` returns `202 Accepted`.\nThe status endpoint is authoritative: webhook or email notification\ndelivery can fail without hiding the validation result from the caller.\n\nStatus separates receipt, validation, domain acceptance, processing, and\ncompletion:\n\n- `received` means Axiom has durably received the submission.\n- `validation_failed` means the submission failed asynchronous validation.\n- `accepted` means validation has passed far enough for domain processing.\n- `processing_failed` means domain processing failed after acceptance.\n- `completed` means processing completed and any resulting domain\n reference is visible in the response where available.\n\nNo domain event or assertion exists until the ingress record reaches an\naccepted/processing/completed state.\n", "tags": [ "Ingress" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "ingress_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Assigned ingress record identifier returned by `POST /v1/ingress/events`." } ], "responses": { "200": { "description": "Current tenant-scoped ingress status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "status_url", "submitted_at", "updated_at", "event_type", "correlation_id", "idempotency_key" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "status": { "type": "string", "enum": [ "received", "queued", "validating", "validation_failed", "accepted", "processing", "processing_failed", "completed", "expired", "cancelled", "dead_lettered" ] }, "stage": { "type": "string", "description": "Current validation or processing stage where applicable", "example": "url_validation" }, "status_url": { "type": "string", "description": "Relative URL for this status resource" }, "submitted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" }, "correlation_id": { "type": "string", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "idempotency_key": { "type": "string" }, "domain_event_id": { "type": "string", "nullable": true, "description": "Resulting domain event identifier when processing has created one", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/IngressStatusError" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/IngressStatusTrailEvent" } } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "data": { "id": "491eb158-40d7-5094-9cf3-3e7a7b38fab6", "status": "validation_failed", "stage": "url_validation", "status_url": "/v1/ingress/events/491eb158-40d7-5094-9cf3-3e7a7b38fab6", "submitted_at": "2026-03-12T09:30:05Z", "updated_at": "2026-03-12T09:30:08Z", "event_type": "external.event.received", "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "idempotency_key": "external-ingress:event-2026-03-12-001", "errors": [ { "code": "URL_UNREACHABLE", "message": "The supplied evidence URL could not be reached within the validation window.", "field": "payload.evidence_url", "retryable": true } ], "events": [ { "status": "received", "stage": "receipt", "recorded_at": "2026-03-12T09:30:05Z", "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008" }, { "status": "validation_failed", "stage": "url_validation", "recorded_at": "2026-03-12T09:30:08Z", "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "errors": [ { "code": "URL_UNREACHABLE", "message": "The supplied evidence URL could not be reached within the validation window.", "field": "payload.evidence_url", "retryable": true } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "published-429-response", "headers": [ "Retry-After", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset" ], "numeric_commitment": "tenant-policy-runtime", "limit_source": "active tenant rate_limit_policies.limit", "window_source": "active tenant rate_limit_policies.window_secs", "enforcement": "gateway-rate-limit-runtime" } }, "x-axiom-operation-safety": { "mutation": 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/mailroom/webhook-endpoints": { "post": { "operationId": "registerWebhookEndpoint", "summary": "Register a webhook endpoint", "description": "Registers or updates a tenant-scoped outbound webhook endpoint.\n\nThis is an alpha transport-configuration surface governed by the\nMailroom transport registry, not an ordinary product API operation.\nIt records where outbound webhook deliveries may be sent and how the\ndelivery should be authenticated. Event subscription catalogues and\ndelivery routing rules are not yet published as a public self-service\ncontract. Do not send `event_types`, event schemas, routing rules,\nordering keys, or replay policy in this request; those semantics are\ngoverned separately before publication.\n\nSecrets are supplied by reference only. Do not send raw secret material\nin the request body.\n\nFor `auth_method=hmac_sha256`, each outbound delivery includes:\n- `X-Axiom-Delivery-Id`: typed `whd_` durable delivery id.\n- `X-Correlation-ID`: support trace id for the delivery workflow.\n- `X-Webhook-Timestamp`: Unix seconds in UTC.\n- `X-Webhook-Signature`: `sha256=` where the digest is\n `HMAC-SHA256(secret, X-Webhook-Timestamp + \".\" + raw request body bytes)`.\n\nReceivers should reject missing, malformed, stale, or mismatched\nsignatures before processing the payload. A five-minute replay window is\nthe alpha recommendation unless the issued integration runbook specifies\na stricter tenant policy.\n\nOutbound webhook delivery is at-least-once. Exactly-once delivery,\nglobal ordering, and per-endpoint ordering are not guaranteed in the\nalpha public contract. The same `X-Axiom-Delivery-Id` is reused across\nretry attempts for one delivery record, but it is not a stable canonical\nevent id across endpoints, event streams, or schema revisions. Receivers\nmust be idempotent and tolerate duplicate, delayed, and out-of-order\ndeliveries.\n\n**Response format:** Canonical success envelope.\n", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "auth_method", "max_retries", "backoff_seconds" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Tenant-scoped endpoint name. Reusing the same name updates\nmutable endpoint settings.\n", "example": "primary-events" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL where webhook payloads will be delivered.\nRuntime validation rejects non-HTTPS URLs and known private,\nloopback, link-local, and non-routable targets.\n", "example": "https://receiver.example.com/axiom/webhooks" }, "description": { "type": "string", "description": "Human-readable description of this endpoint's purpose.", "example": "Primary outbound event receiver" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ], "default": "hmac_sha256", "description": "Authentication method for webhook deliveries.\n- hmac_sha256: HMAC signature over timestamp and raw body bytes.\n- bearer_token_ref: bearer token resolved from auth_secret_ref at dispatch time.\n- none: unsigned delivery; admitted only where tenant policy allows it.\n", "example": "hmac_sha256" }, "auth_secret_ref": { "type": "string", "writeOnly": true, "description": "Opaque secret reference resolved by the Mailroom dispatcher.\nRequired when auth_method is hmac_sha256 or bearer_token_ref.\nRaw secret material must not be sent in this field.\n", "example": "ref:webhooks/primary-events-signing-key" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the endpoint is active" }, "max_retries": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Number of retry attempts after the first delivery attempt.", "example": 3 }, "backoff_seconds": { "type": "array", "description": "Retry backoff values in seconds. The array length must equal\nmax_retries; each value must be between 1 and 3600 seconds.\n", "items": { "type": "integer", "minimum": 1, "maximum": 3600 }, "example": [ 10, 30, 60 ] } }, "additionalProperties": false }, "examples": { "hmac_endpoint": { "summary": "HMAC-signed endpoint", "value": { "name": "primary-events", "url": "https://receiver.example.com/axiom/webhooks", "description": "Primary outbound event receiver", "auth_method": "hmac_sha256", "auth_secret_ref": "ref:webhooks/primary-events-signing-key", "max_retries": 3, "backoff_seconds": [ 10, 30, 60 ], "enabled": true } }, "unsigned_endpoint": { "summary": "Unsigned endpoint admitted by tenant policy", "value": { "name": "test-events", "url": "https://receiver.example.com/axiom/test-webhooks", "description": "Test event receiver", "auth_method": "none", "max_retries": 0, "backoff_seconds": [], "enabled": false } } } } } }, "responses": { "200": { "description": "Webhook endpoint updated idempotently.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "auth_method", "max_retries", "backoff_seconds", "enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$", "description": "Assigned typed webhook-endpoint identifier.", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "description": "Tenant-scoped endpoint name." }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ] }, "max_retries": { "type": "integer" }, "backoff_seconds": { "type": "array", "items": { "type": "integer" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "additionalProperties": true } ] } } } }, "201": { "description": "Webhook endpoint registered.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "auth_method", "max_retries", "backoff_seconds", "enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^whe_[A-Za-z0-9_-]+$", "description": "Assigned typed webhook-endpoint identifier.", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "description": "Tenant-scoped endpoint name." }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "hmac_sha256", "bearer_token_ref", "none" ] }, "max_retries": { "type": "integer" }, "backoff_seconds": { "type": "array", "items": { "type": "integer" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "additionalProperties": true } ] }, "example": { "data": { "id": "whe_7f8a9b0c1d234567890abcdef0123456", "name": "primary-events", "url": "https://receiver.example.com/axiom/webhooks", "description": "Primary outbound event receiver", "auth_method": "hmac_sha256", "max_retries": 3, "backoff_seconds": [ 10, 30, 60 ], "enabled": true, "created_at": "2026-03-12T12:30:00Z", "updated_at": "2026-03-12T12:30:00Z" }, "status": "success" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/mailroom/outbox/webhook-deliveries/{delivery_id}": { "get": { "description": "Contract authority for GET /v1/mailroom/outbox/webhook-deliveries/{delivery_id} (getWebhookDeliveryStatus) in the Events/Assertions portfolio. This contract records semantic authority for the existing runtime-owned operation; runtime proof remains with the owning remediation finding.", "operationId": "getWebhookDeliveryStatus", "parameters": [ { "description": "Path parameter `delivery_id`.", "in": "path", "name": "delivery_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.45 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": "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "responses": { "202": { "description": "Accepted \u2014 operation enqueued/applied per the envelope contract." }, "400": { "description": "Validation error (fail-loud)." }, "403": { "description": "Operating-tenant scope or permission denied." } }, "security": [ { "BearerAuth": [ "mailroom:webhook:read" ] } ], "summary": "Get Webhook Delivery Status", "tags": [ "Event", "assertions", "contract-authority", "audit-remediation" ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "bare", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "bare", "error_profile": "bare", "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": "nonstandard", "scopes": [ "mailroom:webhook:read" ], "required_permissions": [ "mailroom:webhook: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" ], "scope_exception": "One or more published scope names do not use the canonical resource:action form in API 0.1.45." }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-nonread", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/audit/recent": { "get": { "operationId": "getRecentAuditEntries", "summary": "Get recent audit entries", "description": "Returns recent audit log entries for the tenant, ordered by timestamp\ndescending (newest first).\n\nAudit entries record all significant actions: resource creation, updates,\ndeletions, state transitions, authentication events, and compliance checks.\n\nSupports filtering by subject type and cursor-based pagination. Legacy\nlimit/offset pagination is rejected; clients must use page[size] and\npage[after].\n", "tags": [ "Audit" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "$ref": "#/components/parameters/CorrelationId" }, { "name": "page[size]", "in": "query", "required": false, "description": "Maximum number of audit entries to return in this cursor page (default 10, max 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "page[after]", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor by the previous page", "schema": { "type": "string" } }, { "name": "subject_type", "in": "query", "required": false, "description": "Filter by subject type (e.g. policy, claim, party, vendor, product).\nWhen omitted, returns entries for all subject types.\n", "schema": { "type": "string" }, "example": "policy" } ], "responses": { "200": { "description": "List of recent audit entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRecentListResponse" }, "example": { "data": [ { "id": "c8c1b574-fb94-5f72-9f6b-7ace8245889b", "action": "state_transition", "subject_type": "claim", "subject_id": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "actor": "claims-adjudicator@tenant.example.com", "details": { "from_state": "open", "to_state": "under_investigation", "reason": "Assigned to motor assessor for vehicle inspection" }, "correlation_id": "efd67197-fa63-51e3-a961-e418dfc35008", "timestamp": "2026-03-12T14:22:00Z" }, { "id": "21d38436-2690-509f-b28a-b7a4753669c4", "action": "created", "subject_type": "policy", "subject_id": "cc347178-b31f-571d-8ed1-b2513427d36f", "actor": "onboarding-service", "details": { "product_code": "motor-comprehensive", "policy_number": "POL-US-2026-00142" }, "timestamp": "2026-03-12T14:15:00Z" } ], "status": "success", "meta": { "page_size": 10, "has_more": true, "next_cursor": "eyJwZXJmb3JtZWRfYXQiOiIyMDI2LTAzLTEyVDE0OjE1OjAwWiIsImlkIjoiYjBjMWQyZTMtZjRhNS02Nzg5LTAxMjMtNDU2Nzg5YWJjZGVmIn0" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "cursor", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "cursor", "request_parameters": [ "page[size]", "page[after]" ], "consumer_posture": "cursor-page", "response_metadata": [ "meta.next_cursor", "meta.page_size" ] }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "subject_type" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/roles/{roleId}": { "delete": { "operationId": "revokePartyRole", "summary": "Revoke a party role", "description": "Revoke an active role assignment from a Party. The role assignment remains\npart of the Party history and audit record; this operation changes its\nactive status rather than deleting historical evidence.\n", "tags": [ "Party" ], "security": [ { "BearerAuth": [ "parties:revoke-role" ] } ], "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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id" }, "description": "Party role assignment identifier to revoke." } ], "responses": { "200": { "description": "Party role revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyRoleRevocationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "parties:revoke-role" ], "required_permissions": [ "parties:revoke-role" ], "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.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/parties/{id}/balance": { "get": { "operationId": "getPartyBalance", "summary": "Get a party balance", "description": "Return the ledger-derived balance for a Party, optionally scoped by\nproduct, policy, cover, category, role, and as-of time. The response is\ncomputed from runtime ledger entries and is read-only.\n", "tags": [ "Party" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique party identifier" }, { "name": "product_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this product." }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this policy." }, { "name": "cover_id", "in": "query", "required": false, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Limit the balance to entries associated with this cover." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit the balance to a ledger category." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit the balance to a tenant `catalogue.role_types` code." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Compute the balance as of this RFC3339 timestamp. Defaults to the current instant." }, { "name": "decompose", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include balance computation explanation details when true." } ], "responses": { "200": { "description": "Party balance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyBalanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "explicit-filters" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "explicit-filters", "filter_parameters": [ "product_id", "policy_id", "cover_id", "category", "role", "decompose" ] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/premiums/{id}/collect": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Premium identifier. Accepts the canonical `prm_...` typed-prefix form or a UUID.", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "post": { "operationId": "postPremiumsIdCollect", "tags": [ "Premium" ], "summary": "Collect a premium payment", "description": "Record a collected premium payment as a balanced ledger transaction with one debit entry and one or more per-allocation credit entries. The request is idempotent by business event: replay returns the original transaction with `is_replay=true` and no duplicate ledger entries.\n", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-collections" ] }, "attributes": { "type": "object", "required": [ "payment_id" ], "properties": { "payment_id": { "type": "string", "description": "Payment identifier for the collection event.", "example": "pay_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "collected_at": { "type": "string", "format": "date-time", "description": "Business timestamp for the collection. Omitted means the API records the current time.", "example": "2026-04-01T10:00:00Z" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "examples": { "collect": { "summary": "Collected premium payment", "value": { "data": { "type": "premium-collections", "attributes": { "payment_id": "pay_01h9xg2c7e8f4a5b6c7d8e9f0a", "collected_at": "2026-04-01T10:00:00Z" } } } } } } } }, "responses": { "200": { "description": "Idempotent replay of an already-posted collection.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-collections" ] }, "id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "transaction_id", "is_replay", "debit_entry", "credit_entries" ], "properties": { "transaction_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "is_replay": { "type": "boolean", "enum": [ true ] }, "debit_entry": { "$ref": "#/components/schemas/PremiumCollectionLedgerEntry" }, "credit_entries": { "type": "array", "items": { "$ref": "#/components/schemas/PremiumCollectionLedgerEntry" } } }, "additionalProperties": false } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false } } } }, "201": { "description": "Premium collection posted.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "premium-collections" ] }, "id": { "type": "string", "description": "Ledger transaction identifier.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "attributes": { "type": "object", "required": [ "transaction_id", "is_replay", "debit_entry", "credit_entries" ], "properties": { "transaction_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "is_replay": { "type": "boolean" }, "debit_entry": { "$ref": "#/components/schemas/PremiumCollectionLedgerEntry" }, "credit_entries": { "type": "array", "items": { "$ref": "#/components/schemas/PremiumCollectionLedgerEntry" } } }, "additionalProperties": false } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "success" ] } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "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": "missing-contract-gap", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication" ], "tenant_context_exception": "This authenticated operation does not publish an X-Tenant-Context header contract in API 0.1.45. Treat tenant-context handling as an explicit contract gap until the operation is deepened." }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "not-safe-gap", "tenant_context": "missing-contract-gap", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/benefits/{id}/claims-ratio": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "get": { "operationId": "getBenefitsIdClaimsRatio", "tags": [ "Benefit" ], "x-axiom-runtime-availability": { "status": "unavailable", "reason": "Runtime serves the canonical quarantine501Handler until the premium claims-ratio aggregation is rewritten against canonical claim items.", "source": "runtime source" }, "summary": "Benefit claims-ratio route under schema reconciliation", "description": "This route is intentionally unavailable in alpha. It remains present for route accountability, but consumers must use the benefit balance and available-benefit routes until the claims-ratio aggregation has a canonical claim-item implementation.\n", "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Benefit claims-ratio aggregation is unavailable during schema reconciliation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "limited", "published": true, "authorisation": "not-callable-until-runtime-support-lands", "alpha_access_required": true, "production_ready": false, "note": "Published for route accountability in API 0.1.45; this operation returns 501 until runtime support lands." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "missing-contract-gap", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication" ], "tenant_context_exception": "This authenticated operation does not publish an X-Tenant-Context header contract in API 0.1.45. Treat tenant-context handling as an explicit contract gap until the operation is deepened." }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "not-safe-gap", "tenant_context": "missing-contract-gap", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/audit": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "get": { "operationId": "getClaimsIdAudit", "tags": [ "Claim" ], "summary": "Get claim audit trail", "description": "Returns the tenant-scoped audit trail for the claim after verifying the claim exists for the operating tenant.\n", "responses": { "200": { "description": "Claim audit entries retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRecentListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "missing-contract-gap", "tenant_context_authority": "not-required", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication" ], "tenant_context_exception": "This authenticated operation does not publish an X-Tenant-Context header contract in API 0.1.45. Treat tenant-context handling as an explicit contract gap until the operation is deepened." }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": false, "write_allowed": false, "agent_invocation": "not-safe-gap", "tenant_context": "missing-contract-gap", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/me/tenants": { "get": { "operationId": "getMeTenants", "tags": [ "Identity" ], "summary": "List admitted tenants", "description": "Returns the tenants admitted for the authenticated actor. Use the returned tenant selection data to request a server-minted tenant context.", "responses": { "200": { "description": "Admitted tenant list for the authenticated actor.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "granting_role" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9a-hjkmnp-tv-z]{26}$", "description": "Tenant identifier admitted for this authenticated actor.", "example": "tnt_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Tenant display name.", "example": "Example Tenant" }, "granting_role": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Role granting access to the tenant.", "example": "tenant_operator" } } } }, "meta": { "type": "object", "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of admitted tenants returned." }, "limit": { "type": "integer", "minimum": 0, "description": "Offset-pagination page size currently returned by the alpha tenant-admission endpoint." }, "offset": { "type": "integer", "minimum": 0, "description": "Offset-pagination start index currently returned by the alpha tenant-admission endpoint." } } } }, "additionalProperties": true } ] } } } }, "401": { "description": "Bearer token missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "No tenant admission is available for this actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "bootstrap-not-required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "admitted-tenant-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "bootstrap-read", "tenant_context": "bootstrap-not-required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/me/tenant-context": { "post": { "operationId": "postMeTenantContext", "tags": [ "Identity" ], "summary": "Mint tenant context", "description": "Mints a server-authoritative tenant-context token for one admitted tenant. Use that token as the X-Tenant-Context header on tenant-scoped API calls.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tenant_id" ], "properties": { "tenant_id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9a-hjkmnp-tv-z]{26}$", "description": "Tenant identifier selected from GET /v1/me/tenants.", "example": "tnt_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" } } } } } }, "responses": { "200": { "description": "Tenant context minted for an admitted tenant.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data", "status" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "tenant_context_token", "tenant_id", "expires_at" ], "properties": { "tenant_context_token": { "type": "string", "minLength": 1, "description": "Server-minted token for X-Tenant-Context on tenant-scoped requests.", "example": "" }, "tenant_id": { "type": "string", "format": "typed-prefix-id", "pattern": "^tnt_[0-9a-hjkmnp-tv-z]{26}$", "description": "Tenant identifier bound into the token.", "example": "tnt_01arz3ndektsv4rrffq69g5fav", "x-axiom-identifier-shape": "typed-prefix" }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC expiry timestamp.", "example": "2026-08-10T12:00:00Z" } } } }, "additionalProperties": true } ] } } } }, "400": { "description": "Tenant selection payload is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer token missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The selected tenant is not admitted for this actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "legacy-envelope", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "legacy-envelope", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "bootstrap-not-required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "admitted-tenant-authorisation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.45 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "bootstrap-mint-restricted", "tenant_context": "bootstrap-not-required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "parameters": { "CatalogueRefPath": { "name": "catalogue-ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Logical catalogue identifier (slug, e.g. `icd-10-za`)." }, "CatalogueRelationshipRefPath": { "name": "catalogue-ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Logical catalogue identifier (e.g. `icd-10-za`)." }, "CorrelationHeader": { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Correlation id for request tracing." }, "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for end-to-end tracing.\nIf not provided, the server generates one automatically.\nThe response always includes this header for support reference.\n", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 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" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-supplied idempotency key for replay-safe mutation requests.\n\nThe server scopes the key to the tenant, HTTP method, and matched path.\nA replay with the same key and same payload returns the original response.\nA replay with the same key and a different payload returns `409 CONFLICT`.\nA concurrent replay while the first request is still in flight returns\n`409 CONFLICT` with `Retry-After`.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "example": "idem-payment-20260821-001" }, "ReplacementIdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Replacement workflow identifier (prp_ typed-prefix).", "example": "prp_01j1234567890abcdefghijk" }, "TenantHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)." }, "TenantIdHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "description": "Server-minted tenant-context token (TCT) in request header.\n\n**Required** for all tenant-scoped requests. Obtain it from\n`POST /v1/me/tenant-context` after discovering accessible tenants via\n`GET /v1/me/tenants`. The TCT is a short-lived HMAC-signed token that\ncarries the selected tenant and the authenticated account subject; the\nclient-supplied tenant selectors are not accepted.\n\nThe API verifies the token, confirms it belongs to the authenticated actor, re-checks the live grant, and applies tenant isolation for the request.\n", "schema": { "type": "string" }, "example": "" } }, "schemas": { "ActivateProductRequest": { "type": "object", "properties": { "activated_by": { "type": "string", "deprecated": true, "description": "Retired compatibility field. Product activation attribution is derived from the authenticated actor context and this value is ignored.\n", "example": "usr_3f8a" } }, "additionalProperties": false }, "AddBusinessRuleRequest": { "type": "object", "required": [ "code", "name", "rule_type", "expression", "priority" ], "properties": { "code": { "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_.:-]+$", "description": "Machine-readable rule code (must be unique within the ruleset)", "example": "max-sum-insured" }, "name": { "type": "string", "description": "Human-readable rule name", "example": "Maximum Sum Insured Limit" }, "rule_type": { "type": "string", "enum": [ "validation", "calculation", "condition", "action", "commission_rate", "commission_split", "group_discount", "discount_composition" ], "description": "Classification of the rule's purpose", "example": "validation" }, "expression": { "type": "string", "description": "CEL expression for rule evaluation. Both complex expressions\n(e.g., \"cover.sum_insured <= 50000000\") and bare literals\n(e.g., \"25000\") are valid CEL. JSON request facts may bind numeric\nvalues as CEL double values; use explicit int(), uint(), or double()\nconversions when an operator requires a specific numeric type.\n", "example": "25000" }, "description": { "type": "string", "nullable": true, "description": "Human-readable explanation of the rule", "example": "Sum insured must not exceed KES 50,000,000 for standard home contents policies" }, "priority": { "type": "integer", "description": "Execution priority (lower executes first)", "example": 20 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional rule metadata", "example": { "regulatory_ref": "IRA-KE-2025-HC-7" } }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "Structured conditions evaluated before the expression" }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" }, "description": "Actions to execute when the rule evaluates to true" } }, "additionalProperties": false }, "AddCoverItemRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "example": "gp-consultation", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "example": "GP Consultation" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Catalogue-driven cover-item kind code (e.g. benefit, peril).", "example": "benefit", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "classification": { "type": "string" }, "triggers": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/AddCoverTermRequest" } } }, "additionalProperties": false }, "AddCoverRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "description": "Short code for this coverage section", "example": "TPL-BODILY", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Third-Party Bodily Injury" }, "description": { "type": "string", "description": "Detailed description of coverage", "example": "Covers liability for bodily injury to third parties arising from vehicle use" }, "type": { "type": "string", "enum": [ "basic", "optional", "rider" ], "description": "Coverage type within the product", "example": "basic" }, "sum_insured": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 100000000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "deductible": { "type": "integer", "format": "int64", "nullable": true, "description": "Excess amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 50000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "cover_items": { "type": "array", "nullable": true, "description": "CRS-3: nested cover items, each with its own terms. Persisted as the full\ncanonical cover.* row graph in one atomic transaction.\n", "items": { "$ref": "#/components/schemas/AddCoverItemRequest" } }, "cover_terms": { "type": "array", "nullable": true, "description": "CRS-3: nested cover-level terms (conditions, limits, exclusions).", "items": { "$ref": "#/components/schemas/AddCoverTermRequest" } } }, "additionalProperties": false }, "AddCoverTermRequest": { "type": "object", "required": [ "code", "name", "type" ], "properties": { "code": { "type": "string", "example": "annual-limit", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "example": "Annual Limit" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Term type (condition | limit | exclusion | excess).", "example": "limit", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "expression": { "type": "string", "description": "Rule expression for the term (rules-as-data)." }, "boundary": { "$ref": "#/components/schemas/HierarchyTermBoundary" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true } }, "additionalProperties": false }, "AddPartyGroupMemberRequest": { "type": "object", "description": "Exactly one of party_id or group_id must be supplied. Passing neither\nor both is rejected with 400. fail-loud.\n", "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "group_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time", "description": "Defaults to now() server-side when omitted" } }, "additionalProperties": false }, "ArchiveIngestResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/archiveObjectDTO" } }, "required": [ "data" ], "additionalProperties": true } ] }, "AssembleEvidencePackRequest": { "type": "object", "required": [ "name", "record_ids" ], "properties": { "name": { "type": "string", "description": "Descriptive name for the evidence pack", "example": "Policy POL-2026-00089 \u2014 Underwriting Evidence Pack" }, "record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of evidence record IDs to include in the pack", "example": [ "c0e531a6-9deb-53a8-873b-9736a707f52b", "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237" ] }, "assembled_by": { "type": "string", "description": "Identifier of the user or service assembling the pack", "example": "underwriting-service" } }, "additionalProperties": false }, "AssignGroupRoleRequest": { "type": "object", "required": [ "role_type", "context" ], "properties": { "role_type": { "type": "string", "enum": [ "sponsor", "provider", "beneficiary", "accepted_provider_network" ], "example": "accepted_provider_network" }, "context": { "type": "object", "required": [ "entity_type", "entity_id" ], "properties": { "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item" ], "example": "product" }, "entity_id": { "type": "string", "example": "CM-MED-01", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "effective_from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AuditRecentEntry": { "type": "object", "required": [ "id", "action", "subject_type", "subject_id", "actor", "timestamp" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Audit entry identifier", "x-axiom-identifier-shape": "uuid" }, "action": { "type": "string", "description": "Action performed. Common values include created, updated, deleted,\nstate_transition, login, evaluation, and approval.\n", "example": "state_transition" }, "subject_type": { "type": "string", "description": "Type of the entity acted upon", "example": "claim" }, "subject_id": { "type": "string", "description": "Identifier of the entity acted upon", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor": { "type": "string", "description": "Identifier of the user or service that performed the action.", "example": "claims-adjudicator@tenant.example.com" }, "details": { "type": "object", "additionalProperties": true, "description": "Action-specific details. For state_transition, includes from_state and\nto_state. For updates, includes changed fields.\n", "example": { "from_state": "open", "to_state": "under_investigation", "reason": "Assigned to assessor for inspection" } }, "correlation_id": { "type": "string", "format": "uuid", "description": "Request correlation ID for tracing", "x-axiom-identifier-shape": "uuid" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the action occurred", "example": "2026-03-12T14:22:00Z" } }, "additionalProperties": false }, "AuditRecentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRecentEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "AuthorisationTransition": { "type": "object", "required": [ "id", "logical_authorisation_id", "entity_type", "entity_id", "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id", "valid_from", "asserted_from" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "logical_authorisation_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "entity_type": { "type": "string", "enum": [ "claim" ] }, "entity_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string" }, "authorisation_kind": { "type": "string" }, "authorising_actor": { "type": "string", "format": "uuid" }, "authorised_scope": { "type": "object", "additionalProperties": true }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "nullable": true }, "governing_version_kind": { "type": "string", "nullable": true }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true }, "compliance_outcome": { "type": "string", "nullable": true }, "compliance_list_version": { "type": "string", "nullable": true }, "compliance_list_authority": { "type": "string", "nullable": true }, "decision_date": { "type": "string", "format": "date-time" }, "explanation_node_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true }, "valid_from": { "type": "string", "format": "date-time" }, "asserted_from": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time", "readOnly": true } }, "additionalProperties": false }, "BalanceExplanation": { "type": "object", "required": [ "inputs", "rule_version", "computation", "entry_ids" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Input facts used for the balance computation. Supports explainability\nby recording the exact parameters that produced this result.\n", "example": { "account_code": "PREM-RCV-001", "date_from": "2026-01-01T00:00:00Z", "date_to": "2026-03-10T23:59:59Z", "include_pending": false } }, "rule_version": { "type": "string", "description": "Version identifier of the balance computation rule applied (as-was semantics)", "example": "balance-calc-v2.1.0" }, "computation": { "type": "string", "description": "Human-readable description of the computation method", "example": "Sum of posted credits minus posted debits for account PREM-RCV-001" }, "entry_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of ledger entry IDs included in this balance calculation", "example": [ "50447be1-27bd-5a7a-b51c-edce72303e3f", "ba8f3ab8-3beb-55dc-874f-040a4f50529a" ] } }, "additionalProperties": false }, "BalanceResult": { "type": "object", "required": [ "account_code", "as_of", "currency", "amount", "entry_count", "explanation" ], "properties": { "account_code": { "type": "string", "description": "Account code for which the balance was computed", "example": "PREM-RCV-001" }, "as_of": { "type": "string", "format": "date-time", "description": "Point-in-time at which the balance was computed", "example": "2026-03-10T23:59:59Z" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO 4217 currency code", "example": "usd" }, "amount": { "type": "integer", "format": "int64", "description": "Net balance amount (debits minus credits) as of the specified timestamp in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 4525075, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "entry_count": { "type": "integer", "description": "Number of ledger entries included in the balance computation", "example": 128 }, "explanation": { "$ref": "#/components/schemas/BalanceExplanation" } }, "additionalProperties": false }, "BalanceResultResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "BindQuoteRequest": { "type": "object", "required": [ "payment_method", "bound_by" ], "properties": { "payment_method": { "type": "string" }, "bound_by": { "type": "string" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Bind-time parties (must match quote snapshot if provided)" } }, "additionalProperties": false }, "BindQuoteResult": { "type": "object", "required": [ "quote_id" ], "description": "Result of a successful quote bind operation", "properties": { "quote_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_id": { "type": "string", "description": "Created policy ID (optional, may be absent in multi-product binds)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Created policy IDs for multi-product binds" }, "premium_ids": { "type": "array", "items": { "type": "string" }, "description": "Created premium record IDs" }, "allocation_explanation_tree_id": { "type": "string", "description": "Explanation tree for premium allocation.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" }, "description": "Created ledger entry IDs" } }, "additionalProperties": false }, "BindQuoteResultResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BindQuoteResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "BusinessRule": { "type": "object", "required": [ "id", "rule_id", "code", "name", "rule_type", "expression", "priority", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique identifier for this rule instance within the ruleset", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "x-axiom-identifier-shape": "uuid" }, "rule_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Canonical rule identifier (shared across versions)", "example": "c89309e9-11d4-5c80-95cc-5bc9b4b9857c", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Machine-readable rule code for cross-referencing", "example": "min-driver-age", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable rule name", "example": "Minimum Driver Age Rule" }, "rule_type": { "type": "string", "enum": [ "validation", "calculation", "condition", "action", "commission_rate", "commission_split", "group_discount", "discount_composition" ], "description": "Classification of the rule's purpose.\n- validation: Checks data correctness and completeness\n- calculation: Computes a derived value\n- condition: Controls conditional evaluation\n- action: Produces an action result\n- commission_rate: Computes a commission rate\n- commission_split: Computes a commission split\n- group_discount: Computes a group discount\n- discount_composition: Composes discount rules\n", "example": "validation" }, "expression": { "type": "string", "description": "CEL (Common Expression Language) expression that evaluates this rule.\nMust be deterministic and side-effect free. JSON request facts may bind\nnumeric values as CEL double values; use explicit int(), uint(), or\ndouble() conversions when an operator requires a specific numeric type\n(for example, int(applicant.age) % 5 == 0).\n", "example": "applicant.age >= 18 && applicant.age <= 75" }, "description": { "type": "string", "nullable": true, "description": "Human-readable explanation of what this rule does and why", "example": "Drivers must be between 18 and 75 years old for standard motor cover" }, "priority": { "type": "integer", "description": "Execution priority within the ruleset. Lower numbers execute first.\nRules with the same priority may execute in any order.\n", "example": 10 }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Lifecycle status of this individual rule.\n- draft: Under development\n- active: Available for evaluation\n- deprecated: No longer evaluated in new transactions\n", "example": "active" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible metadata for the rule (e.g. regulatory reference, risk category)", "example": { "regulatory_ref": "FSCA-PPR-2018-S4.3", "risk_category": "driver_eligibility" } }, "conditions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "Structured conditions evaluated before the main expression" }, "actions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/RuleAction" }, "description": "Actions to execute when the rule evaluates to true" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\"). Each\nentry explains one element of the rule (e.g. a CEL term) for a human reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated (e.g. a CEL term, a limit, a value_type)." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when this rule was created", "example": "2026-01-10T08:30:00Z" } }, "additionalProperties": false }, "BusinessRuleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessRule" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CalculationAttributes": { "type": "object", "description": "Method-conditional calculator attributes; method-specific keys are omitted when not applicable.", "required": [ "paid_amount_minor", "earned_amount_minor", "unearned_amount_minor", "rounding_mode" ], "properties": { "paid_amount_minor": { "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" }, "earned_amount_minor": { "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" }, "unearned_amount_minor": { "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" }, "rounding_mode": { "type": "string", "enum": [ "floor_minor_unit" ] }, "day_count_convention": { "type": "string", "description": "Present for `method=pro_rata`." }, "short_rate_table_version": { "type": "string", "description": "Present for `method=short_rate`." }, "minimum_earned_amount_minor": { "type": "integer", "format": "int64", "description": "Present for `method=minimum_earned`.", "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" } }, "additionalProperties": false }, "CatalogueRelationship": { "type": "object", "required": [ "id", "source_catalogue", "source_code", "target_catalogue", "target_code", "relationship_type", "scope", "effective_from" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "crl_01ARZ3NDEKTSV4RRFFQ69G5FAV", "x-axiom-identifier-shape": "typed-prefix" }, "source_catalogue": { "type": "string" }, "source_code": { "type": "string" }, "target_catalogue": { "type": "string" }, "target_code": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "parent_of", "maps_to", "member_of", "qualifies", "excludes", "bundles_with", "supersedes", "interacts_with" ] }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true }, "scope": { "type": "string", "enum": [ "universal", "jurisdiction", "tenant" ] }, "jurisdiction": { "type": "string", "nullable": true }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "CatalogueRelationshipBody": { "type": "object", "required": [ "target_catalogue", "target_code", "relationship_type", "scope", "effective_from" ], "properties": { "source_catalogue": { "type": "string", "description": "Optional on the single-create endpoint (defaults from\n:catalogue-ref). REQUIRED on the batch endpoint. When set,\nMUST equal the path value \u2014 silent override is forbidden.\n" }, "source_code": { "type": "string", "description": "Optional on the single-create endpoint (defaults from\n:code). REQUIRED on the batch endpoint when source_catalogue\nis set.\n" }, "target_catalogue": { "type": "string" }, "target_code": { "type": "string" }, "relationship_type": { "type": "string", "enum": [ "parent_of", "maps_to", "member_of", "qualifies", "excludes", "bundles_with", "supersedes", "interacts_with" ] }, "attributes": { "type": "object", "additionalProperties": true }, "scope": { "type": "string", "enum": [ "universal", "jurisdiction", "tenant" ] }, "jurisdiction": { "type": "string", "description": "Required when scope=jurisdiction." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "CertificateProjection": { "type": "object", "required": [ "policy_id", "party_id", "version_id", "roles", "effective_from" ], "properties": { "policy_id": { "type": "string", "description": "Typed-prefix policy identifier (pol_\u2026)", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "party_id": { "type": "string", "description": "Identifier of the member party", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "version_id": { "type": "string", "description": "Typed-prefix policy-version identifier (pov_\u2026) at as_of time", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Active role names for this member at as_of time" }, "effective_from": { "type": "string", "format": "date-time", "description": "When this member's coverage became effective" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "When this member's coverage ends (null = currently active)" } }, "additionalProperties": false }, "CertificateResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CertificateProjection" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Claim": { "type": "object", "required": [ "id", "claim_number", "event_id", "policy_id", "status", "primary_party_id", "event_date", "reported_date", "total_claimed_amount", "description", "priority", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim identifier", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "claim_number": { "type": "string", "description": "Human-readable claim reference number", "readOnly": true, "example": "CLM-2026-00042" }, "event_id": { "type": "string", "format": "uuid", "description": "Reference to the insured event that triggered this claim", "example": "4cbb0168-4d04-535d-969b-927f53d9c96c", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Reference to the policy under which this claim is made", "example": "41866ac2-9965-5dac-b793-aabd56eadcbd", "x-axiom-identifier-shape": "uuid" }, "status": { "$ref": "#/components/schemas/ClaimStatus" }, "primary_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the primary claimant party", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" }, "event_date": { "type": "string", "format": "date-time", "description": "Date and time when the insured event occurred", "example": "2026-02-15T14:30:00Z" }, "reported_date": { "type": "string", "format": "date-time", "description": "Date and time when the claim was reported", "example": "2026-02-16T09:00:00Z" }, "total_claimed_amount": { "type": "integer", "format": "int64", "readOnly": true, "deprecated": true, "description": "Derived, read-only compatibility field. Equal to SUM(claim_items.claimed_amount). No longer stored as a stored field (governed contract). Amount in the smallest currency unit (e.g. cents). Exact integer representation.\n", "example": 4500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "description": { "type": "string", "description": "Free-text description of the claim circumstances", "example": "Rear-end collision at intersection of Main St and 5th Ave. Third-party vehicle damage and whiplash injury to driver." }, "priority": { "$ref": "#/components/schemas/ClaimPriority" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for tenant-specific claim data", "example": { "loss_location": "London, Greater London", "police_report_number": "MET-2026-LDN-3321", "weather_conditions": "clear" } }, "claim_items": { "type": "array", "nullable": true, "description": "Individual line items making up this claim", "items": { "$ref": "#/components/schemas/ClaimItem" } }, "fraud_score": { "type": "string", "nullable": true, "readOnly": true, "description": "Fraud detection score as exact decimal string in [0, 1]. Null when fraud scoring has not been evaluated for this claim. Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0.25" }, "fraud_status": { "type": "string", "readOnly": true, "enum": [ "not_evaluated", "clear", "suspicious", "confirmed_fraud" ], "description": "Fraud evaluation status. Closed enum \u2014 no other values are valid. Legacy value \"fraudulent\" is a compatibility alias for ingest only; API responses always use \"confirmed_fraud\".\n", "example": "not_evaluated" }, "requires_investigation": { "type": "boolean", "readOnly": true, "description": "Derived from fraud_score >= investigation_threshold. False when fraud scoring has not been evaluated.\n", "example": false }, "is_subrogated": { "type": "boolean", "description": "Whether this claim involves subrogation against a third party.", "example": false }, "subrogation_status": { "type": "string", "readOnly": true, "enum": [ "not_identified", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Subrogation lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_identified" }, "recovery_status": { "type": "string", "readOnly": true, "enum": [ "none", "pending", "partial", "completed", "abandoned" ], "description": "Recovery lifecycle status. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "none" }, "assessments": { "type": "array", "nullable": true, "description": "Assessment records for this claim", "items": { "$ref": "#/components/schemas/ClaimAssessment" } }, "payments": { "type": "array", "nullable": true, "description": "Payment records for this claim", "items": { "$ref": "#/components/schemas/ClaimPayment" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim was last updated", "readOnly": true, "example": "2026-02-20T11:30:00Z" } }, "additionalProperties": false }, "ClaimAssessment": { "type": "object", "required": [ "id", "claim_id", "assessment_type", "assessed_by", "assessed_at", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique assessment identifier", "readOnly": true, "example": "cla_01j9zxkp8wqrm2n4v6t5s3d7f6", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the assessed claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "assessment_type": { "type": "string", "description": "Type of assessment performed (e.g. initial, supplementary, independent, medical)", "example": "initial" }, "assessed_by": { "type": "string", "description": "Identifier of the assessor (user ID or external reference)", "example": "assessor-jvd-001" }, "assessed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the assessment was completed", "example": "2026-02-18T16:00:00Z" }, "status": { "type": "string", "enum": [ "approved", "denied", "partial" ], "description": "Assessment outcome status:\n- `approved`: Full claim amount approved\n- `denied`: Claim denied \u2014 no amount approved\n- `partial`: Partial amount approved \u2014 less than total claimed\n", "example": "approved" }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Total amount approved by this assessment. Null if denied.", "nullable": true, "additionalProperties": true }, "denial_reason": { "type": "string", "nullable": true, "description": "Reason for denial or partial denial (null if approved)", "example": null }, "notes": { "type": "string", "nullable": true, "description": "Free-text assessor notes", "example": "All claimed items verified against repair quotations. Approved less R3,000 excess." }, "rule_results": { "type": "array", "nullable": true, "description": "Results from automated rule evaluations during assessment", "items": { "$ref": "#/components/schemas/RuleEvaluationResult" } } }, "additionalProperties": false }, "ClaimItem": { "type": "object", "required": [ "id", "claim_id", "item_type", "description", "claimed_amount", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Unique claim item identifier", "readOnly": true, "example": "cli_01j9zxkp8wqrm2n4v6t5s3d7f5", "x-axiom-identifier-shape": "typed-prefix" }, "claim_id": { "type": "string", "format": "typed-prefix-id", "description": "Reference to the parent claim", "readOnly": true, "example": "clm_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "item_type": { "type": "string", "description": "Category of the claim item (e.g. vehicle_damage, medical, property, liability)", "example": "vehicle_damage" }, "description": { "type": "string", "description": "Detailed description of the claimed item", "example": "Rear bumper replacement and respray \u2014 2024 Toyota Corolla" }, "claimed_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Amount claimed for this item (exact integer minor units + lowercase ISO-4217 currency code)." }, "approved_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount approved by assessor. Null if not yet assessed.", "nullable": true, "additionalProperties": true }, "paid_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Amount actually paid for this item. Null if not yet paid.", "nullable": true, "additionalProperties": true }, "service_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date when the service or repair was performed", "example": "2026-03-01T08:00:00Z" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value attributes for this claim item", "example": { "repair_shop": "Cape Auto Body", "part_numbers": [ "TB-2024-RR-01", "PS-2024-FW-03" ] } }, "status": { "type": "string", "description": "Current status of this claim item", "example": "approved", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "salvage_status": { "type": "string", "readOnly": true, "enum": [ "not_applicable", "identified", "pursuing", "partial", "completed", "abandoned" ], "description": "Salvage lifecycle status for this claim item. Closed enum \u2014 canonical recovery vocabulary locked under the contract. Terminal states: completed, abandoned.\n", "example": "not_applicable" }, "salvage_amount": { "type": "string", "readOnly": true, "description": "Salvage recovery amount as exact decimal string in the smallest currency unit (e.g. cents). Emitted as a JSON string, never a JSON number (governed contract).\n", "example": "0", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the claim item was created", "readOnly": true, "example": "2026-02-16T09:00:00Z" } }, "additionalProperties": false }, "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" }, "ClaimResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ClaimStatus": { "type": "string", "enum": [ "submitted", "under_review", "assessed", "partial_approval", "denied", "paid", "closed" ], "description": "Claim entity lifecycle status. The claim lifecycle follows this state machine:\n\n```\nsubmitted -> under_review -> assessed ---------> paid -> closed\n +-> partial_approval -> paid -> closed\n +-> denied ----------------------> closed\n```\n\nTransitions:\n- `submitted` -> `under_review`: Claim enters active review and triage\n- `under_review` -> `assessed`: Full approval \u2014 assessment approves total claimed amount\n- `under_review` -> `partial_approval`: Partial approval \u2014 approved amount is less than claimed\n- `under_review` -> `denied`: Claim denied \u2014 no amount approved\n- `assessed` -> `paid`: Payment disbursed for fully approved claim\n- `partial_approval` -> `paid`: Payment disbursed for partially approved claim\n- `paid` -> `closed`: Claim lifecycle complete after payment\n- `denied` -> `closed`: Claim lifecycle complete after denial\n\nNote: The assessment outcome (approved, denied, partial) is recorded on\n`ClaimAssessment.status`, not on `Claim.status`. The claim entity status\nreflects the overall lifecycle position.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nPer-value descriptions:\n- `submitted`: Claim has been filed and is awaiting initial review\n- `under_review`: Claim is under active assessment by an assessor\n- `assessed`: Assessment complete with full approval; claim is payable\n- `partial_approval`: Assessment complete with partial approval; claim is payable for the approved amount\n- `denied`: Claim has been denied following assessment; no payment will be made\n- `paid`: Payment has been disbursed to the claimant\n- `closed`: Claim lifecycle is complete (paid, denied, or otherwise resolved)\n", "example": "submitted" }, "Commission": { "type": "object", "required": [ "id", "role_type", "commission_type", "rate", "calculation_basis", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique commission structure identifier", "example": "fa590161-dad2-5a57-84d1-4a71d6457a36", "x-axiom-identifier-shape": "uuid" }, "role_type": { "type": "string", "description": "The intermediary role this commission applies to (e.g. broker, agent)", "example": "broker" }, "commission_type": { "type": "string", "description": "Type of commission (e.g. initial, renewal, override)", "example": "initial" }, "rate": { "type": "number", "format": "double", "description": "Commission rate (as a decimal, e.g. 0.10 for 10%)", "example": 0.1 }, "min_amount": { "type": "integer", "format": "int64", "nullable": true, "description": "Minimum commission amount per transaction in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 5000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "max_amount": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum commission amount per transaction in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 500000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "calculation_basis": { "type": "string", "description": "What the commission rate is applied to (e.g. gross_premium, net_premium)", "example": "gross_premium" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this commission structure is currently active", "example": "active" } }, "additionalProperties": false }, "CommissionAmount": { "type": "object", "required": [ "role_type", "amount", "commission_type" ], "properties": { "role_type": { "type": "string", "description": "Role of the commission recipient (e.g. broker, underwriting_agent, lead_generator)", "example": "broker" }, "amount": { "type": "integer", "format": "int64", "description": "Commission amount in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 5750, "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" }, "commission_type": { "type": "string", "description": "Type of commission (e.g. initial, renewal, override)", "example": "initial" } }, "additionalProperties": false }, "ComplianceReport": { "type": "object", "required": [ "evaluation_id", "generated_at", "compliance_assertion", "findings", "explanation_tree_id" ], "properties": { "evaluation_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "compliance_assertion": { "type": "boolean", "description": "Always false under the governed contract \u2014 reports are evidence-enabling, not compliance-asserting" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/JurisdictionFinding" } }, "ruleset_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PackVersionRef" } }, "explanation_tree_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "ComplianceReportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ComplianceReport" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ContactInfo": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$", "description": "Phone number in E.164 format" }, "preferred_contact_method": { "type": "string", "enum": [ "email", "phone", "mail" ], "description": "Preferred contact method" } }, "additionalProperties": false }, "Cover": { "type": "object", "required": [ "id", "code", "name", "type", "sum_insured", "deductible", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique cover identifier", "example": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code identifying this coverage section", "example": "INPATIENT", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name of the coverage section", "example": "Inpatient Hospital Cover" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of what this cover provides", "example": "Covers hospitalisation, surgery, and intensive care unit stays" }, "type": { "type": "string", "enum": [ "basic", "optional", "rider" ], "description": "Coverage type within the product.\n- basic: Core coverage included by default\n- optional: Coverage that can be added at the policyholder's discretion\n- rider: Supplementary coverage attached to a base cover\n", "example": "basic" }, "sum_insured": { "type": "integer", "format": "int64", "description": "Maximum amount payable under this cover in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 50000000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "deductible": { "type": "integer", "format": "int64", "description": "Amount the insured must pay before the cover responds in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 100000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for cover-specific configuration", "example": { "waiting_period_days": 30, "co_payment_percentage": 20 } }, "status": { "type": "string", "enum": [ "active", "deprecated", "retired" ], "description": "Cover lifecycle status.\n- active: Cover is currently available within the product\n- deprecated: Cover is superseded and retained for as-was auditability\n- retired: Cover is no longer available and retained for reconstruction\n", "example": "active" }, "cover_items": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CoverItem" }, "description": "Catalogue-governed cover items associated with this cover" }, "cover_terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/HierarchyTerm" }, "description": "Terms (conditions, limits, exclusions) specific to this cover" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\") explaining\nthe cover for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "CoverItem": { "type": "object", "required": [ "id", "code", "name", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique cover provision identifier", "example": "6a56e7ae-2e1b-511f-9306-7b24909cc710", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this cover provision", "example": "SURG-BEN", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Surgical Benefit" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the cover provision", "example": "Covers elective and emergency surgical procedures" }, "type": { "type": "string", "description": "Catalogue-driven cover-item kind code. `benefit` and `peril` are seeded\nsector vernacular values, not the closed validity set; tenants may add\ngoverned kind values through the cover-item-kinds catalogue.\n", "example": "benefit", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "classification": { "type": "string", "nullable": true, "description": "Optional classification or grouping for the cover provision", "example": "medical" }, "triggers": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Event types or conditions that trigger this cover provision", "example": [ "hospitalisation", "day_surgery" ] }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/HierarchyTerm" }, "description": "Terms specific to this cover provision" } }, "additionalProperties": false }, "CoverListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cover" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "CoverResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cover" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CreateEvidenceRecordRequest": { "type": "object", "required": [ "record_type", "subject_type", "subject_id", "content" ], "properties": { "record_type": { "type": "string", "description": "Classification of the evidence record", "example": "rule_evaluation" }, "subject_type": { "type": "string", "description": "Type of the entity this evidence pertains to", "example": "policy" }, "subject_id": { "type": "string", "description": "Identifier of the subject entity", "example": "e316666f-e293-5ccc-81a8-8a12fe4094c5", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content": { "type": "object", "additionalProperties": true, "description": "Structured evidence payload", "example": { "evaluation": "premium_calculation", "inputs": { "vehicle_value": 450000, "driver_age": 32, "claims_history": 0 }, "rule_version": "motor-pricing-v2.0.1", "base_premium": 8100, "loadings": [], "discounts": [ { "type": "no_claims_bonus", "percentage": 0.2 } ], "final_premium": 6480 } }, "created_by": { "type": "string", "description": "Identifier of the creating user or service", "example": "pricing-engine" } }, "additionalProperties": false }, "CreateEvidenceRecordResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedEvidenceRecordResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "CreateIntegrationInput": { "type": "object", "required": [ "system_name", "data_categories", "data_direction", "transfer_method" ], "properties": { "system_name": { "type": "string", "description": "Name of the external system", "example": "MediCheck Claims API" }, "data_categories": { "type": "array", "items": { "type": "string" }, "description": "Categories of data exchanged", "example": [ "health_records", "claim_documents" ] }, "data_direction": { "type": "string", "enum": [ "ingress", "egress", "bidirectional" ], "description": "Direction of data flow relative to Axiom", "example": "ingress" }, "transfer_method": { "type": "string", "description": "Technical method for data transfer", "example": "rest_api" } }, "additionalProperties": false }, "CreatePartyGroupRequest": { "type": "object", "required": [ "display_name" ], "properties": { "group_type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "Defaults to static when omitted" }, "display_name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "external_id": { "type": "string", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "id_namespace": { "type": "string", "default": "tenant" }, "membership_rule_id": { "type": "string", "description": "Required when group_type = dynamic", "example": "rule-party-age-over-18", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "CreatePartyRequest": { "type": "object", "required": [ "party_type", "attributes" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "description": "Optional client-provided identifier. If omitted, the server generates one.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "party_type": { "type": "string", "enum": [ "individual", "organization", "system" ], "description": "Identity classification of the party. Contextual participation such as broker, provider, agent, adjuster, or assessor belongs to PartyRole.role_type.", "example": "individual" }, "external_id": { "type": "string", "description": "External identifier from source_system. If supplied, source_system is required.", "example": "BRK-000123", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Party-specific data (name, contact details, identifiers, etc.)", "example": { "first_name": "Takeshi", "last_name": "Yamamoto", "email": "t.yamamoto@example.jp", "phone": "+81312345678" } }, "created_by": { "type": "string", "description": "Identifier of the user or service creating this party", "example": "admin-user-001" }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required when status is merged; rejected for non-merged statuses.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "CreatePaymentRequest": { "type": "object", "required": [ "amount", "payment_method" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Payment amount (exact integer minor units + lowercase ISO-4217 currency code). Must be non-empty." }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the payment purpose", "example": "Ad-hoc premium payment \u2014 health gap cover" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the associated resource (premium, claim, etc.)", "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Type of the referenced resource", "example": "premium" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the party associated with this payment. Must be a valid party ID within the tenant.", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value metadata", "example": { "source": "broker-portal", "broker_id": "BRK-0042" } } }, "additionalProperties": false }, "CreatePolicyRequest": { "type": "object", "required": [ "product_id", "effective_date", "expiry_date", "parties" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "Identifier of the product to issue the policy under", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "effective_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "description": "Date from which the policy provides coverage. YYYY-MM-DD and RFC3339\ndate-time are accepted; runtime normalizes the value before persistence.\n", "example": "2026-04-01" }, "expiry_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "description": "Date on which the policy coverage ends. YYYY-MM-DD and RFC3339 date-time\nare accepted; runtime normalizes the value before persistence.\n", "example": "2027-03-31" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Policy-specific data", "example": { "sum_insured": 250000, "territory": "EU" } }, "parties": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyPartyRequest" }, "description": "Parties to assign to the policy (at least one required)" }, "created_by": { "type": "string", "description": "Optional caller-supplied audit label. Authoritative actor attribution is\nderived from the authenticated actor context when omitted.\n", "example": "agent-user-005" }, "binding_mode": { "type": "string", "enum": [ "individual", "group" ], "default": "individual", "description": "Policy binding mode. When omitted, defaults to \"individual\" for backward\ncompatibility. Set to \"group\" for master policy inception (group/employer/family).\n" }, "group_context": { "type": "object", "nullable": true, "description": "Required when binding_mode=group; must be absent for individual policies.\nDescribes the group contract metadata.\n", "properties": { "group_type": { "type": "string", "enum": [ "family", "employer" ], "description": "Type of group arrangement" }, "group_name": { "type": "string", "description": "Optional display name for the group" }, "external_group_ref": { "type": "string", "description": "Optional caller-supplied correlation key for the group" } }, "additionalProperties": false } }, "additionalProperties": false }, "CreateProductRequest": { "type": "object", "required": [ "product_code", "name", "type", "description", "currency", "covers", "terms", "attributes" ], "properties": { "product_code": { "type": "string", "description": "Human-readable product code (must be unique within the tenant)", "example": "MOTOR-TPL-2026" }, "name": { "type": "string", "description": "Display name of the product", "example": "Motor Third-Party Liability" }, "type": { "type": "string", "description": "Product classification", "example": "motor", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "description": { "type": "string", "description": "Detailed description of the product", "example": "Mandatory third-party liability cover for motor vehicles" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code. Uppercase input is accepted and normalized to lowercase canonical form by the runtime.", "example": "zar" }, "attributes": { "type": "object", "required": [ "base_premium" ], "properties": { "base_premium": { "type": "number", "description": "Required base premium amount in the smallest currency unit (e.g. cents). Must be positive. governed contract: no silent defaults.", "example": 15000, "x-axiom-money-classification": "json-number-money-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money", "x-axiom-money-risk": "json-number-can-lose-exactness" } }, "additionalProperties": true, "description": "Product configuration including required base_premium. governed contract: missing base_premium is an error, not a default.", "example": { "base_premium": 15000, "region": "EMEA", "regulatory_class": "compulsory" } }, "covers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AddCoverRequest" }, "description": "Required: at least one coverage section (governed contract: no silent defaults)" }, "terms": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ProductTermCreate" }, "description": "Required: at least one configurable term (governed contract: no silent defaults). Create-shaped: no server-minted term id (governed contract / governed contract)." } }, "additionalProperties": false }, "CreateQuoteRequest": { "type": "object", "required": [ "effective_date", "expiry_date" ], "description": "Exactly one of pricing_snapshot_id, products, or product_id must be provided.\npricing_snapshot_id and products are mutually exclusive (422 PRICING_INPUT_CONFLICT).\nIf none is provided, returns 422 PRICING_INPUT_REQUIRED.\n", "properties": { "pricing_snapshot_id": { "type": "string", "description": "Reference to a prior rate result snapshot (mutually exclusive with products)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "products": { "type": "array", "description": "Inline product + risk_profile pairs (mutually exclusive with pricing_snapshot_id)", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "risk_profile": { "type": "object", "additionalProperties": false } }, "additionalProperties": false } }, "product_id": { "type": "string", "description": "Legacy single-product shorthand (backward compatible)", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date", "example": "2026-04-01" }, "expiry_date": { "type": "string", "format": "date", "example": "2027-04-01" }, "underwriting_data": { "type": "object", "additionalProperties": true, "example": { "age": 35, "vehicle_value": 25000 } }, "covers_selected": { "type": "array", "items": { "type": "string" }, "default": [] }, "comparison_ref": { "type": "string", "description": "Links comparison sets for quote comparison" }, "supersedes": { "type": "string", "description": "Quote ID this quote supersedes" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Party snapshot for bind-time matching" } }, "additionalProperties": false }, "CreateReversalResponse": { "type": "object", "required": [ "reversal_entry_id", "original_entry_id", "transaction_id", "content_hash", "created_at" ], "properties": { "reversal_entry_id": { "type": "string", "description": "Ledger entry ID for the reversal entry.", "example": "rev-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_entry_id": { "type": "string", "description": "Ledger entry ID that was reversed.", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "transaction_id": { "type": "string", "description": "Transaction identifier shared by the reversal posting.", "example": "txn-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content_hash": { "type": "string", "description": "Canonical content hash for the reversal entry.", "example": "2f1c0b6e2c8a..." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the reversal was created.", "example": "2026-04-01T09:10:00Z" } }, "additionalProperties": false }, "CreateRulesetRequest": { "type": "object", "required": [ "code", "name", "entity_type", "description" ], "properties": { "code": { "type": "string", "description": "Machine-readable ruleset code (must be unique within the tenant)", "example": "home-contents-ke-v1", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable ruleset name", "example": "Kenya Home Contents Insurance" }, "entity_type": { "type": "string", "enum": [ "claims", "underwriting", "pricing", "claims_assessment", "document_completeness", "discount" ], "description": "Runtime rule lane this ruleset governs", "example": "pricing" }, "description": { "type": "string", "description": "Detailed description of the ruleset purpose", "example": "Validation and pricing rules for home contents cover in Kenya" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional metadata (jurisdiction, product line, etc.)", "example": { "jurisdiction": "KE", "product_line": "home_contents" } }, "base_ruleset": { "type": "string", "nullable": true, "description": "Code of an existing ruleset to use as a template. The new ruleset\ninherits rules from the base, which can then be overridden or extended.\n", "example": "home-contents-generic-v1" } }, "additionalProperties": false }, "CreateSubprocessorRequest": { "type": "object", "description": "JSON:API envelope for subprocessor creation request", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "required": [ "name", "service_scope" ], "properties": { "name": { "type": "string", "description": "Legal name of the subprocessor", "example": "Azure US East" }, "service_scope": { "type": "string", "description": "Services provided by the subprocessor", "example": "Disaster recovery and backup storage" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "CreateVendorRequest": { "type": "object", "description": "JSON:API envelope for vendor creation request", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "required": [ "name", "purpose", "classification", "accessed_data_classes", "integrations" ], "properties": { "name": { "type": "string", "description": "Legal or trading name of the vendor", "example": "MediCheck Health Services" }, "purpose": { "type": "string", "description": "Business purpose for engaging this vendor", "example": "Medical underwriting and claims verification" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Vendor data-access classification (A-E)", "example": "C" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Data classification labels for data the vendor will access", "example": [ "health", "personal_identifiable" ] }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Initial vendor status (defaults to draft if omitted)", "example": "draft" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional link to an existing Party record", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/CreateIntegrationInput" }, "description": "Initial integrations to create with the vendor" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "CreatedEvidenceRecordResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence record identifier.", "example": "3ed19703-e2bf-5cc7-80f3-c89ec9ec24b2", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence" ], "description": "JSON:API resource type for evidence records." }, "attributes": { "type": "object", "required": [ "evidence_id", "content_hash", "canonicalization_version" ], "properties": { "evidence_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "content_hash": { "type": "string" }, "canonicalization_version": { "type": "string", "example": "jcs-rfc8785-v1" } }, "additionalProperties": false } }, "additionalProperties": false }, "DeclineQuoteRequest": { "type": "object", "required": [ "reason_code" ], "properties": { "reason_code": { "type": "string", "description": "Machine-readable reason for declining the quote" } }, "additionalProperties": false }, "EndorsementResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyEndorsement" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Error": { "type": "object", "required": [ "status", "title" ], "properties": { "status": { "type": "string", "description": "HTTP status code as a string", "example": "422", "x-axiom-coded-value-classification": "platform-http-status-code" }, "code": { "type": "string", "description": "Application-specific error code", "example": "VALIDATION_ERROR", "pattern": "^[A-Z][A-Z0-9_]*$" }, "title": { "type": "string", "description": "Short, human-readable summary of the error", "example": "Validation Error" }, "detail": { "type": "string", "description": "Human-readable explanation of the error", "example": "Field 'policy_number' is required" }, "help_url": { "type": "string", "format": "uri", "description": "Documentation URL for this error code", "example": "https://developers.afr-dev.axiom.express/api/reference/0.1.45/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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Error" }, "description": "Array of error objects" }, "meta": { "$ref": "#/components/schemas/ErrorMeta" } }, "additionalProperties": false }, "ErrorSource": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the field that caused the error", "example": "/data/attributes/policy_number" }, "parameter": { "type": "string", "description": "Query parameter that caused the error", "example": "filter[status]" }, "header": { "type": "string", "description": "Header that caused the error", "example": "X-Tenant-Context" } }, "additionalProperties": false }, "EvaluatePartyGroupRequest": { "type": "object", "required": [ "party_id" ], "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "as_of": { "type": "string", "format": "date-time", "description": "Defaults to now() server-side" } }, "additionalProperties": false }, "Event": { "type": "object", "description": "A real-world incident (the events half of the events/assertions paired\nprimitive, governed contract). Read-only projection over the event schema.\n", "required": [ "id", "event_type", "occurred_at", "reported_at", "status" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "Event identity (wire form)", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "event_type": { "type": "string", "description": "Type of incident: accident, illness, theft, damage, death, etc.", "example": "accident" }, "event_subtype": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the incident occurred" }, "reported_at": { "type": "string", "format": "date-time", "description": "When the incident was reported" }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "description": "Event lifecycle status (free-form domain string)", "example": "validated", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "severity": { "type": "string" }, "location": { "type": "string" }, "coordinates": { "type": "object", "additionalProperties": true }, "event_details": { "type": "object", "additionalProperties": true, "description": "Domain-specific incident detail payload" }, "primary_party_id": { "type": "string", "format": "uuid", "nullable": true, "x-axiom-identifier-shape": "uuid" }, "involved_parties": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "policy_id": { "type": "string", "description": "Reference to the policy the incident is reported against", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_object_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "validation_method": { "type": "string" }, "validation_reference": { "type": "string" }, "estimated_loss": { "type": "integer", "format": "int64", "description": "Estimated loss in exact integer minor units (governed contract \u2014 never float), paired with currency", "example": 5000000 }, "currency": { "type": "string", "description": "Lowercase ISO-4217 currency for estimated_loss (governed contract)", "example": "zar" }, "requires_notification": { "type": "boolean" }, "notification_sent": { "type": "string", "format": "date-time", "nullable": true }, "notification_reference": { "type": "string" }, "reported_by": { "type": "string" }, "source_system": { "type": "string" }, "external_reference": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "description": { "type": "string", "description": "Human-readable event description" }, "investigation_notes": { "type": "string" } }, "additionalProperties": false }, "EventReportRequest": { "type": "object", "required": [ "event_data" ], "properties": { "event_data": { "type": "string", "description": "JSON object (as a string) describing the event. Supported fields mirror\nthe Event projection's tenant-reportable fields: event_id, event_type,\nevent_subtype, occurred_at, reported_at, policy_id, policy_object_id,\nprimary_party_id, event_details, metadata, description, and the other\noptional event facts exposed on the Event schema.\n" } }, "additionalProperties": { "type": "string", "format": "binary" } }, "EventReportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/eventReportDTO" } }, "required": [ "data" ], "additionalProperties": true } ] }, "EvidencePackResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence pack identifier.", "example": "00548ee3-5ea2-5e09-8975-93b2e0fe033e", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence-pack" ], "description": "JSON:API resource type for evidence packs." }, "attributes": { "type": "object", "required": [ "surface_code", "generated_at", "pack_hash", "evidence_entries" ], "properties": { "surface_code": { "type": "string", "description": "Regulatory surface used to assemble the pack.", "example": "conduct_claims" }, "generated_at": { "type": "string", "format": "date-time", "description": "Time the evidence pack was generated." }, "inputs_fingerprint": { "type": "string", "description": "Deterministic fingerprint of the inputs used for assembly." }, "pack_hash": { "type": "string", "description": "Deterministic hash of the assembled evidence pack." }, "assembly_rules": { "type": "object", "additionalProperties": true, "description": "Compliance pack reference and rule metadata used for assembly." }, "evidence_entries": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Evidence entries included in the pack." } }, "additionalProperties": false } }, "additionalProperties": false }, "EvidenceRecord": { "type": "object", "required": [ "id", "record_type", "subject_type", "subject_id", "content", "content_hash", "created_at", "created_by" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique evidence record identifier", "example": "c0e531a6-9deb-53a8-873b-9736a707f52b", "x-axiom-identifier-shape": "uuid" }, "record_type": { "type": "string", "description": "Classification of the evidence record.\nCommon types: decision_trace, approval_record, compliance_check,\nrule_evaluation, state_transition, document_verification.\n", "example": "decision_trace" }, "subject_type": { "type": "string", "description": "Type of the entity this evidence pertains to\n(e.g. policy, claim, premium, party, ruleset).\n", "example": "claim" }, "subject_id": { "type": "string", "description": "Identifier of the entity this evidence pertains to", "example": "1fcce2e6-d8ac-5e1c-befc-cdbe46da3237", "x-axiom-identifier-classification": "subject-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content": { "type": "object", "additionalProperties": true, "description": "Structured evidence payload. Contents vary by record_type but must\nbe self-contained and reproducible (platform principle \u2014 explainability).\nIncludes inputs, outputs, rule versions, and intermediate results.\n", "example": { "decision": "claim_approved", "inputs": { "claim_amount": 12500, "policy_excess": 2500, "cover_limit": 500000 }, "rule_version": "motor-claims-v3.2.0", "evaluation_steps": [ { "rule": "cover_active_check", "result": true }, { "rule": "excess_applied", "result": true, "excess_amount": 2500 }, { "rule": "within_cover_limit", "result": true } ], "net_payout": 10000 } }, "content_hash": { "type": "string", "readOnly": true, "description": "SHA-256 hash of the content payload. Enables tamper detection\nand integrity verification without inspecting the full content.\n", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the evidence record was created", "example": "2026-03-08T14:22:15Z" }, "created_by": { "type": "string", "readOnly": true, "description": "Identifier of the user or service that created this record", "example": "claims-adjudication-service" } }, "additionalProperties": false }, "EvidenceRecordResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Evidence record identifier.", "example": "3ed19703-e2bf-5cc7-80f3-c89ec9ec24b2", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "evidence" ], "description": "JSON:API resource type for evidence records." }, "attributes": { "type": "object", "required": [ "content_hash", "canonicalization_version", "integrity_status", "actor_type", "actor_id", "actor_original_id", "evidence_type", "entity_id", "entity_type", "occurred_at", "created_at" ], "properties": { "content_hash": { "type": "string" }, "canonicalization_version": { "type": "string", "example": "jcs-rfc8785-v1" }, "integrity_status": { "type": "string" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "evidence_type": { "type": "string" }, "entity_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "entity_type": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false }, "EvidenceRecordResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EvidenceRecordResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "HierarchyTerm": { "type": "object", "required": [ "id", "code", "name", "type", "parent_type", "parent_id" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique term identifier", "example": "d828de91-2a8f-5a4b-96ef-a8b1337ef371", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this term", "example": "MAX-CLAIM-LIMIT", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Maximum Claim Limit" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the term", "example": "Maximum amount claimable per event" }, "type": { "type": "string", "enum": [ "condition", "limit", "exclusion" ], "description": "The kind of term.\n- condition: A prerequisite that must be met for coverage to apply\n- limit: A numeric boundary on coverage (e.g. maximum payout)\n- exclusion: A circumstance under which coverage does not apply\n", "example": "limit" }, "parent_type": { "type": "string", "description": "The type of parent entity (e.g. cover, cover_item)", "example": "cover" }, "parent_id": { "type": "string", "format": "uuid", "description": "Identifier of the parent entity", "example": "5b065930-e739-58e7-a8af-4d690e1dc2f7", "x-axiom-identifier-shape": "uuid" }, "expression": { "type": "string", "nullable": true, "description": "CEL expression for evaluating this term", "example": "claim.amount <= 250000.00" }, "boundary": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/HierarchyTermBoundary" } ], "additionalProperties": true }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "HierarchyTermBoundary": { "type": "object", "description": "Numeric boundaries for limit-type hierarchy terms", "properties": { "min": { "type": "integer", "format": "int64", "nullable": true, "description": "Minimum boundary value in the smallest currency unit (e.g. cents) when monetary, or in the declared unit otherwise. Exact integer representation.", "example": 0 }, "max": { "type": "integer", "format": "int64", "nullable": true, "description": "Maximum boundary value in the smallest currency unit (e.g. cents) when monetary, or in the declared unit otherwise. Exact integer representation.", "example": 50000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "nullable": true, "description": "ISO 4217 currency code (when boundary is monetary)", "example": "EUR" }, "unit": { "type": "string", "nullable": true, "description": "Unit of measurement (when boundary is non-monetary)", "example": "days" } }, "additionalProperties": false }, "IngressStatusError": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "URL_UNREACHABLE", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "message": { "type": "string", "example": "The supplied evidence URL could not be reached within the validation window." }, "field": { "type": "string", "example": "payload.evidence_url" }, "retryable": { "type": "boolean" } }, "additionalProperties": false }, "IngressStatusTrailEvent": { "type": "object", "required": [ "status", "recorded_at", "correlation_id" ], "properties": { "status": { "type": "string", "enum": [ "received", "queued", "validating", "validation_failed", "accepted", "processing", "processing_failed", "completed", "expired", "cancelled", "dead_lettered" ] }, "stage": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "correlation_id": { "type": "string", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "domain_event_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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/IngressStatusError" } } }, "additionalProperties": false }, "Integration": { "type": "object", "required": [ "integration_id", "vendor_id", "system_name", "data_categories", "data_direction", "transfer_method" ], "properties": { "integration_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique integration identifier", "example": "ef3dae92-18c3-52d8-bb19-359e317362d6", "x-axiom-identifier-shape": "uuid" }, "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Vendor this integration belongs to", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "system_name": { "type": "string", "description": "Name of the external system being integrated", "example": "CloudSure Policy API" }, "data_categories": { "type": "array", "items": { "type": "string" }, "description": "Categories of data exchanged through this integration.\nAligns with data classification policy.\n", "example": [ "policy_data", "policyholder_pii", "premium_amounts" ] }, "data_direction": { "type": "string", "enum": [ "ingress", "egress", "bidirectional" ], "description": "Direction of data flow relative to Axiom.\n- ingress: Data flows from vendor into Axiom\n- egress: Data flows from Axiom to vendor\n- bidirectional: Data flows in both directions\n", "example": "bidirectional" }, "transfer_method": { "type": "string", "description": "Technical method used for data transfer\n(e.g. rest_api, sftp, webhook, message_queue, batch_file).\n", "example": "rest_api" } }, "additionalProperties": false }, "IntegrityResult": { "type": "object", "required": [ "entry_id", "status", "failure_code", "computed_hash", "stored_hash", "chain_depth" ], "properties": { "entry_id": { "type": "string", "description": "Ledger entry checked.", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "status": { "type": "string", "enum": [ "PASS", "FAIL" ], "description": "Integrity status for this entry.", "example": "PASS" }, "failure_code": { "type": "string", "description": "Failure code when status is FAIL; empty when the check passes.", "example": "" }, "computed_hash": { "type": "string", "description": "Hash computed from the current canonical entry content.", "example": "2f1c0b6e2c8a..." }, "stored_hash": { "type": "string", "description": "Hash stored with the entry.", "example": "2f1c0b6e2c8a..." }, "chain_depth": { "type": "integer", "description": "Number of lineage links inspected.", "example": 0 } }, "additionalProperties": false }, "IntegrityVerificationResource": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Integrity verification identifier.", "example": "d030a083-6627-5d10-a1ec-de4b762f556b", "x-axiom-identifier-shape": "uuid" }, "type": { "type": "string", "enum": [ "integrity-verification" ] }, "attributes": { "type": "object", "required": [ "verification_id", "expected_hash", "actual_hash", "status", "verified_at" ], "properties": { "verification_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "expected_hash": { "type": "string" }, "actual_hash": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "tampered", "missing", "corrected" ] }, "verified_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false }, "IntegrityVerificationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IntegrityVerificationResource" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Invoice": { "type": "object", "description": "Invoice resource. Field-level shape remains runtime-governed until the invoice resource schema is promoted.", "additionalProperties": true }, "InvoiceListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "InvoiceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": [ "data" ], "additionalProperties": true } ] }, "JurisdictionFinding": { "type": "object", "properties": { "jurisdiction_code": { "type": "string", "example": "ZA" }, "status": { "type": "string", "enum": [ "pass", "fail", "needs_review" ] }, "evidence_references": { "type": "array", "items": { "type": "string" } }, "missing_evidence": { "type": "array", "items": { "type": "string" }, "description": "JSON paths of missing evidence fields" } }, "additionalProperties": false }, "LedgerCorrectionsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LineageNode" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerEntry": { "type": "object", "required": [ "id", "account_code", "entry_type", "amount", "currency", "entry_date", "status", "posted_at", "posted_by", "reference_type", "reference_id" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique ledger entry identifier", "example": "50447be1-27bd-5a7a-b51c-edce72303e3f", "x-axiom-identifier-shape": "uuid" }, "account_code": { "type": "string", "description": "Account code identifying the ledger account.\nFollows a hierarchical naming convention (e.g. premium receivable,\nclaims payable, commission expense).\n", "example": "PREM-RCV-001" }, "entry_type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Type of ledger entry. Every financial transaction records balanced\ndebit and credit entries.\n- debit: Increases asset/expense accounts, decreases liability/revenue accounts\n- credit: Increases liability/revenue accounts, decreases asset/expense accounts\n", "example": "credit" }, "amount": { "type": "integer", "format": "int64", "description": "Monetary amount for this entry in the smallest currency unit (e.g. cents). Always positive; direction is determined by entry_type. Exact integer representation.", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO 4217 currency code", "example": "usd" }, "entry_date": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the accounting date for this entry", "example": "2026-03-01T00:00:00Z" }, "status": { "type": "string", "enum": [ "pending", "posted", "reversed" ], "description": "Current status of the ledger entry.\n- pending: Entry created but not yet posted to the ledger\n- posted: Entry has been posted and affects account balances\n- reversed: Entry has been reversed by a correcting entry\n", "example": "posted" }, "posted_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the entry was posted", "example": "2026-03-01T08:15:30Z" }, "posted_by": { "type": "string", "readOnly": true, "description": "Identifier of the user or service that posted this entry", "example": "premium-collection-service" }, "reference_type": { "type": "string", "description": "Type of the source entity that originated this ledger entry\n(e.g. premium, claim, adjustment).\n", "example": "premium" }, "reference_id": { "type": "string", "format": "uuid", "description": "Identifier of the source entity that originated this entry", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "LedgerEntryListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerIntegrityResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VerifyIntegrityResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LedgerReversalResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateReversalResponse" } }, "required": [ "data" ], "additionalProperties": true } ] }, "LineageNode": { "type": "object", "required": [ "entry_id", "original_entry_id", "reversal_entry_id", "actor_type", "actor_id", "actor_original_id", "reason_code", "content_hash", "business_event_time" ], "properties": { "entry_id": { "type": "string", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_entry_id": { "type": "string", "example": "orig-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "reversal_entry_id": { "type": "string", "example": "rev-http-1", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "example": "human" }, "actor_id": { "type": "string", "example": "user-1", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "example": "user-1", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "reason_code": { "type": "string", "example": "correction" }, "content_hash": { "type": "string", "example": "2f1c0b6e2c8a..." }, "business_event_time": { "type": "string", "format": "date-time", "example": "2026-04-01T09:10:00Z" } }, "additionalProperties": false }, "Money": { "type": "object", "required": [ "amount_minor", "currency_code" ], "properties": { "amount_minor": { "type": "integer", "format": "int64", "description": "Monetary amount in exact integer minor units (e.g. cents for ZAR/USD/EUR). Never float. The minor-unit exponent derives from currency_code \u2014 never hardcoded.", "example": 123456 }, "currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code (e.g. \"zar\"). Must be non-empty; absent currency is a caller error.", "example": "zar" } }, "additionalProperties": false }, "OffsetPaginationMeta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items matching the query", "example": 87 }, "limit": { "type": "integer", "description": "Maximum items per page", "example": 20 }, "offset": { "type": "integer", "description": "Number of items skipped", "example": 40 } }, "additionalProperties": false }, "PackVersionRef": { "type": "object", "properties": { "pack_id": { "type": "string", "format": "uuid", "description": "Compliance pack UUID", "x-axiom-identifier-shape": "uuid" }, "pack_version": { "type": "string", "description": "Semantic version of the pack", "example": "1.0.0" }, "ruleset_id": { "type": "string", "description": "Optional ruleset identifier", "x-axiom-identifier-classification": "ruleset-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_version": { "type": "string", "description": "Optional ruleset version" } }, "additionalProperties": false }, "PaginationMeta": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Current cursor position (can be used for bookmarking)", "example": "eyJpZCI6MTAwfQ==" }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page (null if no more pages)", "example": "eyJpZCI6MTIwfQ==" }, "has_more": { "type": "boolean", "description": "Whether more pages exist after this one", "example": true }, "page_size": { "type": "integer", "description": "Number of items in this page", "example": 20 }, "total_count": { "type": "integer", "description": "Total number of items matching the query.\nMay be omitted for performance on large datasets.\nWhen omitted, use `has_more` to determine if more pages exist.\n", "example": 150 } }, "additionalProperties": false }, "Party": { "type": "object", "required": [ "id", "party_type", "status", "source_system", "attributes", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "description": "Unique party identifier", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "party_type": { "type": "string", "enum": [ "individual", "organization", "system" ], "description": "Identity classification of the party. Contextual participation such as\nbroker, provider, agent, adjuster, or assessor belongs to PartyRole.role_type,\nnot Party.party_type.\n- individual: A natural person (policyholder, claimant, beneficiary)\n- organization: A legal entity (corporate client, reinsurer)\n- system: A non-human system identity used for platform mechanics\n", "example": "individual" }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "description": "Surviving Party identifier when status is merged. Required for status=merged; absent for every other status.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "external_id": { "type": "string", "nullable": true, "description": "Tenant-scoped identifier from the declared source system. Treat as PII-like; do not log raw request bodies containing it.", "example": "BRK-000123", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Extensible key-value pairs for party-specific data (name, date of birth, tax ID, etc.)", "example": { "first_name": "Maria", "last_name": "Eriksson", "date_of_birth": "1985-03-14", "email": "maria.eriksson@example.com" } }, "roles": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PartyRole" }, "description": "Roles assigned to this party across policies and claims" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was created", "example": "2026-01-15T09:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was last updated", "example": "2026-02-20T14:45:00Z" } }, "additionalProperties": false }, "PartyAuditEventItem": { "type": "object", "required": [ "id", "table_name", "operation", "performed_at", "actor_type", "actor_id", "actor_original_id", "rule_versions", "summary" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "table_name": { "type": "string" }, "operation": { "type": "string" }, "old_values": { "type": "object", "additionalProperties": true }, "new_values": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "performed_at": { "type": "string", "format": "date-time" }, "correlation_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "enum": [ "human", "service", "agent" ] }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "outcome": { "type": "string" }, "decision_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "decision-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "operation_code": { "type": "string" }, "purpose": { "type": "string", "description": "Declared business or compliance purpose recorded with the audit event." }, "compliance_category": { "type": "string", "description": "Compliance classification attached to the audit event." }, "data_classification": { "type": "string", "description": "Data classification for the audited payload or access." }, "additional_context": { "type": "object", "additionalProperties": true, "description": "Additional tenant/runtime context captured for the audit event." }, "rule_versions": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" } }, "additionalProperties": false }, "PartyAuditListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyAuditEventItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "PartyBalanceExplanation": { "type": "object", "required": [ "inputs", "rule_version", "computation", "entry_ids" ], "properties": { "inputs": { "type": "object", "additionalProperties": { "type": "string" } }, "rule_version": { "type": "string" }, "computation": { "type": "string" }, "entry_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "PartyBalanceFilter": { "type": "object", "properties": { "product_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "cover_id": { "type": "string", "format": "typed-prefix-id", "nullable": true, "x-axiom-identifier-shape": "typed-prefix" }, "category": { "type": "string", "nullable": true, "x-axiom-coded-value-classification": "tenant-catalogue-category" }, "role": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PartyBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyBalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyBalanceResult": { "type": "object", "required": [ "party_id", "as_of", "currency", "amount", "entry_count" ], "properties": { "party_id": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "as_of": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "description": "Decimal amount rendered as a string to preserve exact wire fidelity.", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "entry_count": { "type": "integer", "minimum": 0 }, "filters": { "$ref": "#/components/schemas/PartyBalanceFilter" }, "explanation": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PartyBalanceExplanation" } ], "additionalProperties": true } }, "additionalProperties": false }, "PartyContactListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactInfo" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyContactResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactInfo" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyDistributionChainResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Distribution chain traversal result", "required": [ "participants" ], "properties": { "participants": { "type": "array", "items": { "type": "object", "required": [ "party_id", "depth", "path" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "depth": { "type": "integer" }, "relationship_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "relationship_type": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "selected_path_rank": { "type": "integer" } }, "additionalProperties": false } }, "explanation": { "type": "object", "nullable": true, "description": "Traversal reasoning under the governed contract.", "properties": { "as_of": { "type": "string", "format": "date-time" }, "start_party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "filters": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time" }, "types": { "type": "array", "items": { "type": "string" } }, "max_depth": { "type": "integer" } }, "additionalProperties": false }, "candidate_paths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "winning_path": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyExternalIDSourceSystem": { "type": "string", "enum": [ "unmapped", "kelevra_native", "broker_crm", "underwriter_pas" ], "description": "Authoritative alpha registry for Party external identifier provenance.\n`external_id` and `source_system` form an exact lookup pair: callers must supply both or neither on list filters, and create/update must include source_system whenever external_id is supplied.\n", "example": "broker_crm" }, "PartyGroup": { "type": "object", "required": [ "id", "group_type", "status", "id_namespace", "display_name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique party-group identifier", "example": "d9af24ca-ffcb-5bed-b8ef-ae867ef80388", "x-axiom-identifier-shape": "uuid" }, "group_type": { "type": "string", "enum": [ "static", "dynamic" ], "description": "Membership resolution strategy.\n- static: members are managed manually via the /members endpoints\n- dynamic: members resolve via a CEL rule referenced by membership_rule;\n on-demand evaluation via POST /evaluate\n", "example": "static" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Lifecycle status. Soft delete flips to inactive \u2014 the group and its\nmemberships are preserved for audit (governed contract).\n", "example": "active" }, "id_namespace": { "type": "string", "description": "Namespace for external_id (DEFAULT tenant)", "example": "tenant" }, "external_id": { "type": "string", "nullable": true, "description": "Optional tenant-supplied identifier, unique per (tenant, id_namespace, group_type)", "example": "acme-employees", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "display_name": { "type": "string", "description": "Human-readable group name", "example": "ACME Employees" }, "description": { "type": "string", "nullable": true, "description": "Free-form purpose / semantics", "example": "All employees of ACME Corp as of the current payroll run" }, "membership_rule": { "type": "object", "nullable": true, "description": "CEL rule reference for dynamic groups. Shape is `{\"rule_id\": \"...\"}`\nreferencing a rule in the shared rules catalog. MUST be null when\ngroup_type = static; MUST be non-null when group_type = dynamic.\n", "additionalProperties": true, "example": { "rule_id": "rule-party-age-over-18" } }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-18T09:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-04-18T09:30:00Z" }, "created_by_actor_type": { "type": "string", "readOnly": true, "description": "Actor attribution under the governed contract", "example": "human" }, "created_by_actor_id": { "type": "string", "readOnly": true, "example": "user-marcus@acme.example", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupAuditEntry": { "type": "object", "required": [ "id", "table_name", "operation", "performed_at", "actor_type", "actor_id", "actor_original_id", "rule_versions", "summary" ], "properties": { "id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "table_name": { "type": "string" }, "operation": { "type": "string" }, "old_values": { "type": "object", "additionalProperties": true }, "new_values": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "performed_at": { "type": "string", "format": "date-time" }, "correlation_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_type": { "type": "string", "enum": [ "human", "service", "agent" ] }, "actor_id": { "type": "string", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "outcome": { "type": "string" }, "decision_id": { "type": "string", "nullable": true, "x-axiom-identifier-classification": "decision-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "operation_code": { "type": "string" }, "rule_versions": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" } }, "additionalProperties": false }, "PartyGroupAuditListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupAuditEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true } ] }, "PartyGroupDetail": { "type": "object", "required": [ "party_group", "members" ], "properties": { "party_group": { "$ref": "#/components/schemas/PartyGroup" }, "members": { "type": "array", "description": "Active memberships as of the query time (or ?as_of=)", "items": { "$ref": "#/components/schemas/PartyGroupMembership" } } }, "additionalProperties": false }, "PartyGroupDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupDetail" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupEvaluationResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupEvaluationResult": { "type": "object", "required": [ "group_id", "party_id", "is_member", "evaluated_at" ], "description": "Read-only dry-run result of evaluating a dynamic group's membership rule\nagainst a candidate party. Does NOT mutate state.\n", "properties": { "group_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "is_member": { "type": "boolean", "description": "Whether the rule accepts this party for this group" }, "rule_id": { "type": "string", "nullable": true, "description": "The rule that was evaluated", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_type": { "type": "string", "nullable": true, "example": "party_grouping" }, "evaluated_at": { "type": "string", "format": "date-time" }, "explanation_summary": { "type": "string", "description": "under the governed contract \u2014 concise trace of which clauses matched or failed", "example": "party_type == individual: matched; attributes.age >= 18: matched" } }, "additionalProperties": false }, "PartyGroupFlatMember": { "type": "object", "required": [ "party_id", "found_at_depth" ], "description": "One party reachable from a group via recursive membership expansion", "properties": { "party_id": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "found_at_depth": { "type": "integer", "minimum": 1, "description": "BFS depth at which this party was first reached (1 = direct member)" }, "via_path": { "type": "array", "items": { "type": "string" }, "description": "Chain of group ids from the start group to this party" }, "membership_id": { "type": "string", "format": "uuid", "description": "The membership row that connected this party at the first depth found", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PartyGroupFlatMemberListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupFlatMember" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroup" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupMembership": { "type": "object", "required": [ "id", "group_id", "member_type", "member_id", "valid_from", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "x-axiom-identifier-shape": "uuid" }, "group_id": { "type": "string", "format": "uuid", "description": "FK to party_groups.id", "x-axiom-identifier-shape": "uuid" }, "member_type": { "type": "string", "enum": [ "party", "group" ], "description": "Polymorphic member kind. `party` means member_id references parties.id;\n`group` means member_id references party_groups.id (nested membership).\n", "example": "party" }, "member_id": { "type": "string", "format": "uuid", "description": "FK to parties.id OR party_groups.id per member_type", "x-axiom-identifier-shape": "uuid" }, "valid_from": { "type": "string", "format": "date-time", "description": "Membership start (inclusive)", "example": "2026-04-18T09:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "nullable": true, "description": "Membership end (exclusive); null = currently active" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by_actor_type": { "type": "string", "readOnly": true }, "created_by_actor_id": { "type": "string", "readOnly": true, "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupMembershipResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupMembership" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupMembershipView": { "type": "object", "required": [ "group_id", "name", "grouping_rule_id", "effective_from", "via_policy_id" ], "properties": { "group_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "name": { "type": "string" }, "grouping_rule_id": { "type": "string", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "via_policy_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "PartyGroupResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroup" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupRole": { "type": "object", "required": [ "id", "role_type", "context", "effective_from" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "x-axiom-identifier-shape": "uuid" }, "role_type": { "type": "string", "enum": [ "sponsor", "provider", "beneficiary", "accepted_provider_network" ], "description": "Role played by the group.\n- sponsor: Group sponsoring a scheme (e.g. employer on a group health policy)\n- provider: Group acting as a service provider\n- beneficiary: Group entitled to benefits\n- accepted_provider_network: Provider-network group accepted on a Product context. Requires composition_type=provider_network on the assignee group and\n entity_type=product on the role context.\n", "example": "sponsor" }, "context": { "type": "object", "required": [ "entity_type", "entity_id" ], "description": "Entity the role is held against (policy, claim, party, etc.)", "properties": { "entity_type": { "type": "string", "example": "policy" }, "entity_id": { "type": "string", "example": "policy-12345", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "effective_from": { "type": "string", "format": "date-time", "example": "2026-04-18T09:30:00Z" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revocation_reason": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PartyGroupRoleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupRole" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyGroupRoleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyGroupRole" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyIdentityItem": { "type": "object", "required": [ "id", "identity_type", "identity_value", "status" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "pti_01J9ZXKP8WQRM2N4V6T5S3D7F5", "x-axiom-identifier-shape": "typed-prefix" }, "identity_type": { "type": "string", "description": "Type of identity document (e.g. passport, national_id, tax_number, company_registration)", "example": "passport" }, "identity_value": { "type": "string", "description": "The identity document number or value", "example": "AB1234567" }, "issuing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code of issuing authority", "example": "GB" }, "expiry_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiry date of the identity document", "example": "2032-06-15" }, "status": { "type": "string", "enum": [ "unverified", "verified", "expired", "revoked" ], "example": "unverified" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, "additionalProperties": false }, "PartyIdentityListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyIdentityItem" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyIdentityResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyIdentityItem" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyLifecycleStatus": { "type": "string", "enum": [ "active", "inactive", "suspended", "deceased", "merged", "opted_out" ], "description": "Current Party lifecycle status.\n- active: Party can participate in transactions.\n- inactive: Party is no longer active.\n- suspended: Party is temporarily suspended pending review.\n- deceased: Natural-person Party is terminally deceased.\n- merged: Duplicate Party has been merged into merged_into_party_id and rejects later Party-scoped mutations.\n- opted_out: Party has opted out of new contact capture; historical contact reads remain available.\n", "example": "active" }, "PartyListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Party" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyPaymentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyPolicyGroupListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyGroupMembershipView" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRelationshipItem": { "type": "object", "description": "Relationship resource per parties.RelationshipResponse", "required": [ "id", "from_party_id", "to_party_id", "relationship_type", "effective_from", "created_by" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "example": "ptr_01J9ZXKP8WQRM2N4V6T5S3D7F6", "x-axiom-identifier-shape": "typed-prefix" }, "from_party_id": { "type": "string", "format": "typed-prefix-id", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-shape": "typed-prefix" }, "to_party_id": { "type": "string", "format": "typed-prefix-id", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "relationship_type": { "type": "string", "description": "Tenant `catalogue.relationship_types` code." }, "effective_from": { "type": "string", "format": "date-time" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "created_by": { "type": "string" } }, "additionalProperties": false }, "PartyRelationshipListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRelationshipItem" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRelationshipResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyRelationshipItem" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Party" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRole": { "type": "object", "required": [ "id", "role_type", "context", "status", "assigned_at" ], "properties": { "id": { "type": "string", "format": "typed-prefix-id", "readOnly": true, "description": "Unique role assignment identifier", "example": "rol_01j9zxkp8wqrm2n4v6t5s3d7f3", "x-axiom-identifier-shape": "typed-prefix" }, "role_type": { "type": "string", "description": "Tenant `catalogue.role_types` code assigned to the party. Bootstrap\nseed codes include policyholder, insured, beneficiary, broker, sponsor,\nand accepted_provider_network, but tenants may govern additional role\ntypes through the catalogue.\n", "example": "policyholder" }, "context": { "$ref": "#/components/schemas/RoleContext" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this role assignment is currently active", "example": "active" }, "assigned_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the role was assigned", "example": "2026-01-15T09:30:00Z" } }, "additionalProperties": false }, "PartyRoleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRole" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartyRole" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleRevocationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "string", "format": "typed-prefix-id", "description": "Revoked role assignment identifier.", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "PartyRoleTypeEntry": { "type": "object", "required": [ "code", "display_name", "universal", "assignable_context_types", "requires_attribution" ], "properties": { "code": { "type": "string", "description": "Wire-stable party role type code.", "example": "policyholder", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "display_name": { "type": "string", "description": "Human-readable role type label.", "example": "Policyholder" }, "universal": { "type": "boolean", "description": "True when the role type is universal across tenants.", "example": true }, "assignable_context_types": { "type": "array", "nullable": true, "description": "Context types where this role type may be assigned.", "items": { "type": "string" }, "example": [ "policy", "policy_item" ] }, "requires_attribution": { "type": "boolean", "description": "True when the role assignment requires actor attribution.", "example": true }, "regulatory_category": { "type": "string", "description": "Regulatory designation when one applies.", "example": "FAIS representative" }, "sector_hint": { "type": "string", "description": "Sector context for non-universal role types.", "example": "health" } }, "additionalProperties": false }, "Payment": { "type": "object", "required": [ "id", "amount", "status", "payment_method", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payment identifier", "readOnly": true, "example": "fc07471c-677f-5d54-b3b0-4172aacb0fcd", "x-axiom-identifier-shape": "uuid" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Payment amount (exact integer minor units + lowercase ISO-4217 currency code)." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the payment purpose", "example": "Monthly premium \u2014 motor comprehensive policy POL-2026-00123" }, "reference_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the associated resource (premium, claim, etc.)", "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "reference_type": { "type": "string", "nullable": true, "description": "Type of the referenced resource (e.g. premium, claim, refund)", "example": "premium" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value metadata for integration and operational data", "example": { "bank_reference": "ABSA-EFT-20260401-0042", "batch_id": "BATCH-2026-04-01", "reconciliation_status": "matched" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment record was created", "readOnly": true, "example": "2026-04-01T06:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the payment record was last updated", "readOnly": true, "example": "2026-04-01T08:30:00Z" }, "processed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the payment was successfully processed (null if not yet processed)", "readOnly": true, "example": "2026-04-01T08:30:00Z" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Reference to the party (policyholder, beneficiary, etc.) associated with this payment. Nullable for backward compatibility with payments created before party linkage.", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" } }, "additionalProperties": false }, "PaymentFrequency": { "type": "string", "enum": [ "monthly", "quarterly", "half_yearly", "annual" ], "description": "Payment schedule frequency:\n- `monthly` \u2014 Payment due every month\n- `quarterly` \u2014 Payment due every 3 months\n- `half_yearly` \u2014 Payment due every 6 months\n- `annual` \u2014 Payment due once per year\n", "example": "monthly" }, "PaymentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentMethod": { "type": "string", "enum": [ "bank_transfer", "credit_card", "debit_order", "cash", "cheque" ], "description": "Supported payment methods:\n- `bank_transfer` \u2014 Electronic funds transfer (EFT) or wire transfer\n- `credit_card` \u2014 Credit card payment via payment gateway\n- `debit_order` \u2014 Recurring debit order (direct debit) from bank account\n- `cash` \u2014 Cash payment (recorded manually, typically at branch)\n- `cheque` \u2014 Cheque payment (subject to clearing period)\n", "example": "debit_order" }, "PaymentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentSchedule": { "type": "object", "required": [ "id", "policy_id", "frequency", "amount", "status", "next_due_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payment schedule identifier", "readOnly": true, "example": "24161ecd-8592-537c-849c-575aea8b40f1", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "pattern": "^pol_[0-9a-z]+$", "description": "Reference to the policy this schedule services, rendered in canonical typed-prefix form.", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-shape": "typed-prefix" }, "frequency": { "$ref": "#/components/schemas/PaymentFrequency" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Scheduled payment amount per period (exact integer minor units + lowercase ISO-4217 currency code)." }, "status": { "$ref": "#/components/schemas/PaymentScheduleStatus" }, "next_due_date": { "type": "string", "format": "date", "description": "Next scheduled payment date", "example": "2026-05-01" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was created", "readOnly": true, "example": "2026-01-15T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was last updated", "readOnly": true, "example": "2026-04-01T08:30:00Z" } }, "additionalProperties": false }, "PaymentScheduleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSchedule" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PaymentScheduleStatus": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ], "description": "Payment schedule lifecycle status:\n- `active` \u2014 Schedule is running and will generate payments on due dates\n- `paused` \u2014 Schedule is temporarily suspended (e.g. payment holiday, dispute)\n- `completed` \u2014 Schedule has run its full term (policy expired or fully paid)\n- `cancelled` \u2014 Schedule has been permanently cancelled\n", "example": "active" }, "PaymentStatus": { "type": "string", "enum": [ "pending", "completed", "cancelled" ], "description": "Payment lifecycle status. This public lifecycle is the Axiom payment command\nlifecycle implemented by the Payment service, not the provider outcome\nvocabulary used internally by Billing/Invoicing traces.\n- `pending` \u2014 Payment has been created and may still be updated, processed, or cancelled.\n- `completed` \u2014 Payment reached the successful terminal state.\n- `cancelled` \u2014 Payment was cancelled before completion.\n", "example": "pending" }, "Policy": { "type": "object", "required": [ "id", "policy_number", "product_id", "status", "effective_date", "expiry_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique policy identifier", "example": "204a5555-2273-5dfd-8bcc-09717add6538", "x-axiom-identifier-shape": "uuid" }, "policy_number": { "type": "string", "readOnly": true, "description": "Human-readable policy number assigned by the system", "example": "POL-2026-000142" }, "product_id": { "type": "string", "format": "uuid", "description": "Identifier of the product this policy is issued under", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "status": { "type": "string", "enum": [ "draft", "quoted", "bound", "active", "lapsed", "cancelled", "expired" ], "description": "Current status of the policy. The policy lifecycle follows this state machine:\n\n```\nquoted -> draft -> bound -> active -> cancelled|lapsed|expired\n```\n\nTransitions:\n- `quoted` -> `draft`: A quote or proposal has been accepted for policy preparation.\n- `draft` -> `bound`: The policy has been reviewed and contractually bound.\n- `bound` -> `active`: The policy has reached its effective date and is providing coverage.\n- `active` -> `cancelled`: Coverage ended before natural expiry.\n- `active` -> `lapsed`: Coverage ended due to non-payment.\n- `active` -> `expired`: Coverage ended at natural expiry.\n\nInvalid transitions return HTTP 422 with error code `INVALID_STATE_TRANSITION`.\n\nPer-value descriptions:\n- `draft`: Policy is being prepared; not yet formally issued or providing coverage\n- `quoted`: Policy proposal exists before contractual binding\n- `bound`: Policy has been contractually bound but is not necessarily active\n- `active`: Policy is in force and providing coverage to the insured parties\n- `lapsed`: Policy coverage ended due to non-payment\n- `cancelled`: Policy coverage ended before natural expiry\n- `expired`: Policy coverage ended at natural expiry\n", "example": "active" }, "effective_date": { "type": "string", "format": "date", "description": "Date from which the policy provides coverage (inclusive)", "example": "2026-03-01" }, "expiry_date": { "type": "string", "format": "date", "description": "Date on which the policy coverage ends (inclusive)", "example": "2027-02-28" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value pairs for policy-specific data", "example": { "sum_insured": 250000, "territory": "EU", "renewal_count": 0 } }, "parties": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PolicyPartyRole" }, "description": "Parties and their roles on this policy" }, "premiums": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PolicyPremiumScheduleItem" }, "description": "Premium schedule for this policy" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the policy was created", "example": "2026-02-28T11:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the policy was last updated", "example": "2026-03-01T09:15:00Z" } }, "additionalProperties": false }, "PolicyBindRequest": { "type": "object", "required": [ "parties", "payment_method", "bound_by" ], "description": "Two bind modes: (1) quote-backed \u2014 provide quote_id; or (2) inline \u2014 provide product_id, effective_date, and expiry_date. parties, payment_method, and bound_by are always required.", "properties": { "quote_id": { "type": "string", "description": "Quote identifier for quote-backed bind. Mutually exclusive with inline fields (product_id, effective_date, expiry_date).", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "description": "Product identifier for inline bind. Required when quote_id is not provided.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp for policy activation. Required for inline bind (when quote_id is not provided)." }, "expiry_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp for policy expiry. Required for inline bind (when quote_id is not provided)." }, "underwriting_data": { "type": "object", "additionalProperties": true }, "parties": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ] } }, "additionalProperties": false } }, "payment_method": { "type": "string" }, "bound_by": { "type": "string" }, "binding_mode": { "type": "string", "enum": [ "individual", "group" ], "default": "individual", "description": "Policy binding mode. Defaults to \"individual\" for backward compatibility. Set to \"group\" for master policy inception." }, "group_context": { "type": "object", "nullable": true, "description": "Required when binding_mode=group; must be absent for individual.", "properties": { "group_type": { "type": "string", "enum": [ "family", "employer" ] }, "group_name": { "type": "string" }, "external_group_ref": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "PolicyBindResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyBindResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyBindResult": { "type": "object", "description": "The bound-policy payload returned in the SuccessEnvelope data field.", "required": [ "policy_id", "policy_number", "status", "premium_breakdown", "bound_at", "premium_id" ], "properties": { "policy_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_number": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "premium_breakdown": { "type": "object", "additionalProperties": true }, "bound_at": { "type": "string", "format": "date-time" }, "premium_id": { "type": "string", "description": "ID of the premium record created during bind (governed contract). Always present on success.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "explanation_tree_id": { "type": "string", "description": "ID of the bind explanation tree (governed contract), when produced.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ledger_entry_ids": { "type": "array", "items": { "type": "string" }, "description": "Ledger entry IDs produced during bind, when applicable." } }, "additionalProperties": false }, "PolicyEndorsement": { "type": "object", "required": [ "id", "policy_id", "endorsement_number", "type", "description", "effective_date", "status", "endorsed_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique endorsement identifier", "example": "93c78f91-646f-56ed-8224-5bf2845cc2bc", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the policy being endorsed", "example": "204a5555-2273-5dfd-8bcc-09717add6538", "x-axiom-identifier-shape": "uuid" }, "endorsement_number": { "type": "string", "readOnly": true, "description": "Sequential endorsement number within the policy", "example": "END-001" }, "type": { "type": "string", "description": "Classification of the endorsement (e.g. amendment, addition, deletion, correction)", "example": "amendment", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "description": { "type": "string", "description": "Human-readable description of what this endorsement changes", "example": "Update insured address and increase sum insured from 250,000 to 300,000" }, "effective_date": { "type": "string", "format": "date", "description": "Date from which the endorsement takes effect", "example": "2026-06-01" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected" ], "description": "Processing status of the endorsement.\n- pending: Endorsement has been submitted but not yet applied\n- applied: Endorsement has been applied to the policy\n- rejected: Endorsement was rejected (e.g. failed validation)\n", "example": "applied" }, "changes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Structured representation of the changes made by this endorsement", "example": { "sum_insured": { "from": 250000, "to": 300000 }, "address": { "from": "10 Downing Street, London", "to": "221B Baker Street, London" } } }, "endorsed_by": { "type": "string", "description": "Identifier of the user or process that created this endorsement", "example": "underwriter-user-003" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the endorsement was created", "example": "2026-05-28T14:00:00Z" } }, "additionalProperties": false }, "PolicyListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyPartyRequest": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "format": "uuid", "description": "Identifier of an existing party to assign to the policy", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "role": { "type": "string", "description": "Role to assign the party on this policy (e.g. policyholder, dependent, insured, beneficiary)", "example": "policyholder" } }, "additionalProperties": false }, "PolicyPartyRole": { "type": "object", "required": [ "party_id", "party_type", "role", "status", "assigned_at" ], "properties": { "party_id": { "type": "string", "format": "uuid", "description": "Identifier of the party", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "party_type": { "type": "string", "description": "Classification of the party (e.g. individual, organization)", "example": "individual" }, "role": { "type": "string", "enum": [ "policyholder", "dependent", "insured", "beneficiary", "agent", "broker" ], "description": "Role of the party on this policy", "example": "policyholder" }, "status": { "type": "string", "enum": [ "active", "inactive", "revoked" ], "description": "Whether this party-role assignment is currently active or has been revoked", "example": "active" }, "assigned_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the party was assigned to this policy", "example": "2026-02-28T11:00:00Z" } }, "additionalProperties": false }, "PolicyPremiumScheduleItem": { "type": "object", "required": [ "id", "amount", "due_date", "status", "payment_method" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique premium instalment identifier", "example": "b3861d98-b3cc-5bd3-a80c-f5325b0c79c4", "x-axiom-identifier-shape": "uuid" }, "amount": { "type": "integer", "format": "int64", "description": "Premium amount due for this instalment in the smallest currency unit (e.g. cents). Exact integer representation.", "example": 11500, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "due_date": { "type": "string", "format": "date", "description": "Date by which the premium payment is due", "example": "2026-04-01" }, "status": { "type": "string", "enum": [ "pending", "paid", "overdue", "waived" ], "description": "Payment status of this premium instalment.\n- pending: Payment has not yet been received and is not overdue\n- paid: Payment has been received and reconciled\n- overdue: Payment was not received by the due date\n- waived: Payment has been waived (e.g. goodwill, correction)\n", "example": "pending" }, "payment_method": { "type": "string", "description": "Method of payment (e.g. debit_order, card, bank_transfer, cash)", "example": "debit_order" } }, "additionalProperties": false }, "PolicyResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyVersion": { "type": "object", "required": [ "id", "policy_id", "version_number", "version_type", "effective_from", "created_at" ], "properties": { "id": { "type": "string", "description": "Typed-prefix policy-version identifier (pov_\u2026)", "readOnly": true, "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "description": "Typed-prefix parent policy identifier (pol_\u2026)", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "version_number": { "type": "integer", "description": "Sequential version number within the policy", "example": 2 }, "version_type": { "type": "string", "enum": [ "issuance", "endorsement", "renewal", "cancellation" ], "description": "Why this version was created" }, "effective_from": { "type": "string", "format": "date-time", "description": "When this version becomes effective (inclusive)" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "When this version ceases to be effective (null = current version)" }, "change_reason": { "type": "string", "description": "Human-readable reason for creating this version" }, "created_by": { "type": "string", "description": "Actor ID who created this version (governed contract)" }, "previous_version": { "type": "string", "description": "ID of the predecessor version (empty for first version)" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the version was created" } }, "additionalProperties": false }, "PolicyVersionListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyVersion" } }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PolicyVersionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyVersion" } }, "required": [ "data" ], "additionalProperties": true } ] }, "Premium": { "type": "object", "required": [ "id", "policy_id", "premium_type", "status", "currency", "base_premium", "total_discount", "total_surcharge", "tax_amount", "net_premium", "final_premium", "installment_count", "installment_amount_minor", "payment_frequency", "effective_date", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique premium identifier", "readOnly": true, "example": "2f7ecef8-dae9-53ff-bf60-c05a7c4b2e7d", "x-axiom-identifier-shape": "uuid" }, "policy_id": { "type": "string", "description": "Reference to the policy this premium belongs to, in the canonical\ntyped-prefix form (`pol_\u2026`, governed contract). Not a bare UUID.\n", "example": "pol_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "party_id": { "type": "string", "description": "Optional reference to the party who owes this premium (the debtor /\npolicyholder), in the canonical typed-prefix form (`pty_\u2026`, governed contract).\nOmitted when unset (absent \u2260 unknown, governed contract).\n", "example": "pty_01h9xg2c7e8f4a5b6c7d8e9f0a", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "premium_type": { "type": "string", "description": "Classifier on the single aggregate premium (NOT a row-multiplier) \u2014 e.g.\n`initial`, `renewal`, `endorsement`, `adjustment` (governed contract). Variation\nis recorded as append-only ledger entries, never a second Premium row.\n", "example": "initial" }, "status": { "$ref": "#/components/schemas/PremiumStatus" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code (e.g. \"zar\", governed contract). Interprets every\n`*_minor` money field on this object; the minor-unit exponent is derived\nfrom this code, never hardcoded.\n", "example": "zar" }, "base_premium": { "type": "integer", "format": "int64", "description": "Base premium before discounts/surcharges/tax, in exact int64 minor units (governed contract, never float).", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "total_discount": { "type": "integer", "format": "int64", "description": "Total discount applied, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "total_surcharge": { "type": "integer", "format": "int64", "description": "Total surcharge applied, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "tax_amount": { "type": "integer", "format": "int64", "description": "Tax component, in exact int64 minor units (governed contract, never float).", "example": 0, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "net_premium": { "type": "integer", "format": "int64", "description": "Canonical net premium (base \u2212 discount + surcharge + tax), in exact int64\nminor units (governed contract, never float). This is the canonical net field \u2014 render\nthis as the money headline, never base_premium.\n", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "final_premium": { "type": "integer", "format": "int64", "description": "Deprecated alias for net_premium \u2014 same value. Read net_premium\ninstead. Retained for back-compat with the PremiumCalculation shape.\n", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "installment_count": { "type": "integer", "description": "Number of instalments the premium is split into (1 = single payment).", "example": 1 }, "installment_amount_minor": { "type": "integer", "format": "int64", "description": "Per-instalment amount, in exact int64 minor units (governed contract, never float).", "example": 125000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "payment_frequency": { "type": "string", "description": "Payment cadence for the premium (e.g. `annual`, `monthly`, `quarterly`).", "example": "annual" }, "effective_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp from which the premium obligation is effective.", "example": "2026-03-01T00:00:00Z" }, "expiry_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp at which the premium obligation expires. Omitted when unset.", "example": "2027-03-01T00:00:00Z" }, "due_date": { "type": "string", "format": "date-time", "description": "RFC3339 timestamp on which the premium is due. Omitted when unset.", "example": "2026-04-01T00:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the premium record was created", "readOnly": true, "example": "2026-03-01T00:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the premium record was last updated", "readOnly": true, "example": "2026-03-15T10:30:00Z" } }, "additionalProperties": false }, "PremiumAdjustment": { "type": "object", "required": [ "rule_name", "adjustment", "description" ], "properties": { "rule_name": { "type": "string", "description": "Name of the rule that produced this adjustment", "example": "young_driver_loading" }, "adjustment": { "type": "integer", "format": "int64", "description": "Adjustment amount in the smallest currency unit (e.g. cents). Positive for loading, negative for discount. Exact integer representation.", "example": 7500 }, "description": { "type": "string", "description": "Human-readable explanation of the adjustment", "example": "Young driver loading \u2014 primary driver age 21, 15% applied to base premium" } }, "additionalProperties": false }, "PremiumCalculation": { "type": "object", "required": [ "product_id", "base_premium", "total_premium", "gross_premium", "discount_total", "net_premium", "calculated_at" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "Reference to the product used for calculation", "example": "e70f8626-562d-58ed-b6a0-ca46a5ce7627", "x-axiom-identifier-shape": "uuid" }, "base_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Base premium before adjustments and commissions." }, "total_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Total premium including all adjustments (gross premium)." }, "gross_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Pre-discount premium equal to total_premium. Provided explicitly for discount transparency." }, "discount_total": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Total discount amount composed from all applicable group discounts." }, "net_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Net premium after deducting discounts (gross_premium - discount_total)." }, "adjusted_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Legacy alias for gross_premium. Deprecated: use gross_premium instead.", "nullable": true, "additionalProperties": true }, "final_premium": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "type": "object", "description": "Legacy alias for net_premium. Deprecated: use net_premium instead.", "nullable": true, "additionalProperties": true }, "adjustments": { "type": "array", "nullable": true, "description": "Itemised premium adjustments applied during calculation", "items": { "$ref": "#/components/schemas/PremiumAdjustment" } }, "discounts": { "type": "array", "nullable": true, "description": "Itemised group discounts applied to the gross premium", "items": { "$ref": "#/components/schemas/PremiumDiscountItem" } }, "commissions": { "type": "array", "nullable": true, "description": "Commission amounts deducted from the net premium", "items": { "$ref": "#/components/schemas/CommissionAmount" } }, "calculated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the premium was calculated", "readOnly": true, "example": "2026-03-10T14:00:00Z" } }, "additionalProperties": false }, "PremiumCalculationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PremiumCalculation" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PremiumCollectionLedgerEntry": { "type": "object", "required": [ "id", "account_code", "entry_type", "amount", "currency", "entity_type", "entity_id" ], "properties": { "id": { "type": "string", "description": "Ledger entry identifier.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "account_code": { "type": "string", "description": "Ledger account code used by the collection posting." }, "entry_type": { "type": "string", "enum": [ "debit", "credit" ] }, "amount": { "type": "integer", "format": "int64", "description": "Exact integer minor-unit amount. Never float.", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code." }, "entity_type": { "type": "string", "description": "Entity type linked to this ledger entry." }, "entity_id": { "type": "string", "description": "Entity identifier linked to this ledger entry.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 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 }, "PremiumDiscountItem": { "type": "object", "required": [ "group_id", "rule_id", "rule_version", "amount", "composition_included", "description" ], "properties": { "group_id": { "type": "string", "description": "Identifier of the group that triggered this discount", "example": "grp-family-001", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 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_id": { "type": "string", "description": "Identifier of the discount rule that was evaluated", "example": "rule-fam-disc-v1", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_version": { "type": "integer", "description": "Version of the discount rule used", "example": 1 }, "amount": { "type": "integer", "format": "int64", "description": "Discount amount in the smallest currency unit (e.g. cents). Always non-negative. Exact integer representation.", "example": 5000, "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "composition_included": { "type": "boolean", "description": "Whether this discount was included in the composed discount total", "example": true }, "description": { "type": "string", "description": "Human-readable explanation of the discount", "example": "Group discount: Family Plan (rule rule-fam-disc-v1 v1)" } }, "additionalProperties": false }, "PremiumListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Premium" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PremiumResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Premium" } }, "required": [ "data" ], "additionalProperties": true } ] }, "PremiumStatus": { "type": "string", "enum": [ "draft", "pending", "active", "expired", "cancelled" ], "description": "Aggregate-premium record lifecycle status (contract rule \u2014 the record lifecycle, not the\ncollection lifecycle):\n- `draft` \u2014 Premium obligation recorded but not yet activated (e.g. a\n manually-entered / imported inflow obligation; never an authoritative\n owed figure, contract rule).\n- `pending` \u2014 Premium is awaiting activation.\n- `active` \u2014 Premium obligation is in force.\n- `expired` \u2014 Premium obligation has lapsed at end of its effective window.\n- `cancelled` \u2014 Premium obligation has been cancelled (e.g. policy\n cancellation mid-term).\n\nNote: `paid` / `overdue` are payment/collection state and live on the\ninstalment (PolicyPremiumScheduleItem.status / /v1/payment-schedules), NOT on\nthe aggregate premium \u2014 relocated, not retired (contract rule, governed contract).\n", "example": "draft" }, "PricingRule": { "type": "object", "required": [ "id", "name", "rule_type", "base_rate", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique pricing rule identifier", "example": "f6011f99-3ae9-58dd-8a88-1e10e88434c6", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Display name of the pricing rule", "example": "Age Rating Factor" }, "rule_type": { "type": "string", "enum": [ "age_factor", "risk_factor", "coverage_factor" ], "description": "Classification of the pricing rule.\n- age_factor: Adjusts premium based on insured's age\n- risk_factor: Adjusts premium based on risk assessment\n- coverage_factor: Adjusts premium based on selected coverage options\n", "example": "age_factor" }, "base_rate": { "type": "number", "format": "double", "description": "Base rate or multiplier for this pricing rule", "example": 1.25 }, "expression": { "type": "string", "nullable": true, "description": "CEL expression for dynamic rate calculation", "example": "age >= 50 ? 1.5 : 1.0" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes for rule configuration", "example": { "age_bands": [ { "min_age": 18, "max_age": 35, "factor": 1 }, { "min_age": 36, "max_age": 50, "factor": 1.25 } ] } }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether this pricing rule is currently applied", "example": "active" } }, "additionalProperties": false }, "Product": { "type": "object", "required": [ "id", "product_code", "name", "type", "status", "description", "currency", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique product identifier", "example": "e74fc507-ba17-5540-871a-0b04cdb6727b", "x-axiom-identifier-shape": "uuid" }, "product_code": { "type": "string", "description": "Human-readable product code used for catalogue reference", "example": "HEALTH-COMP-2026" }, "name": { "type": "string", "description": "Display name of the product", "example": "Comprehensive Health Cover" }, "type": { "type": "string", "description": "Product classification (e.g. life, health, property, motor, liability)", "example": "health", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated", "retired" ], "description": "Product lifecycle status.\n- draft: Product is being configured and is not yet available for policy issuance\n- active: Product is published and available for policy issuance\n- deprecated: Product is superseded and retained for as-was auditability\n- retired: Product is no longer available and retained for reconstruction\n", "example": "draft" }, "description": { "type": "string", "description": "Detailed description of the product and its coverage", "example": "Comprehensive health insurance covering inpatient, outpatient, and dental care" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO-4217 currency code for premiums and limits", "example": "zar" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible key-value pairs for product-specific configuration", "example": { "underwriting_class": "standard", "renewable": true } }, "covers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Cover" }, "description": "Coverage sections included in this product" }, "terms": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ProductTerm" }, "description": "Configurable terms and parameters for the product" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\") explaining\nthe product for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "pricing_rules": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PricingRule" }, "description": "Rules governing premium calculation" }, "commissions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Commission" }, "description": "Commission structures for intermediary roles" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the product was created", "example": "2026-01-10T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the product was last updated", "example": "2026-02-01T16:30:00Z" } }, "additionalProperties": false }, "ProductAuditListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRecentEntry" } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "limit", "offset", "has_more" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductRulesetBinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique binding identifier", "x-axiom-identifier-shape": "uuid" }, "product_id": { "type": "string", "description": "Typed product identifier", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "ruleset_id": { "type": "string", "format": "uuid", "description": "Identifier of the bound ruleset", "x-axiom-identifier-shape": "uuid" }, "ruleset_type": { "type": "string", "description": "Pipeline stage this binding satisfies" }, "ruleset_version": { "type": "integer", "description": "Version number of the bound ruleset" }, "effective_from": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when this binding becomes active" }, "effective_to": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp when this binding was superseded (null if still active)" }, "created_by": { "type": "string", "description": "Actor ID that created the binding" } }, "additionalProperties": false }, "ProductRulesetBindingListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRulesetBinding" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductRulesetBindingResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductRulesetBinding" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProductTerm": { "type": "object", "required": [ "id", "code", "name", "data_type", "required" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique term identifier", "example": "76289c3a-398b-50cc-a1ec-7fa59273eba9", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Short code for this configurable term", "example": "POLICY-TERM-MONTHS", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Policy Term" }, "description": { "type": "string", "nullable": true, "description": "Explanation of this term and how it affects the product", "example": "Duration of the policy in months" }, "data_type": { "type": "string", "description": "Data type for this term's value (e.g. string, integer, number, boolean, date)", "example": "integer" }, "required": { "type": "boolean", "description": "Whether this term must be provided when issuing a policy", "example": true }, "default_value": { "type": "string", "nullable": true, "description": "Default value when not explicitly provided", "example": "12" }, "validations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ValidationRule" }, "description": "Validation rules applied to this term's value" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "ProductTermCreate": { "type": "object", "required": [ "code", "name", "data_type", "required" ], "properties": { "code": { "type": "string", "description": "Short code for this configurable term", "example": "POLICY-TERM-MONTHS", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Display name", "example": "Policy Term" }, "description": { "type": "string", "nullable": true, "description": "Explanation of this term and how it affects the product", "example": "Duration of the policy in months" }, "data_type": { "type": "string", "description": "Data type for this term's value (e.g. string, integer, number, boolean, date)", "example": "integer" }, "required": { "type": "boolean", "description": "Whether this term must be provided when issuing a policy", "example": true }, "default_value": { "type": "string", "nullable": true, "description": "Default value when not explicitly provided", "example": "12" }, "validations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ValidationRule" }, "description": "Validation rules applied to this term's value" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible attributes" } }, "additionalProperties": false }, "ProrationAdjustmentComponent": { "type": "object", "description": "Typed effect emitted by a proration decision.", "required": [ "component_type", "consumer", "affected" ], "additionalProperties": false, "properties": { "component_type": { "type": "string", "enum": [ "money", "premium_earning", "cover_limit", "waiting_period", "cover_period", "savings_fund", "backpay_debt", "entitlement_restoration", "reinsurance", "refusal" ] }, "consumer": { "type": "string", "enum": [ "ledger", "entitlement_balance", "temporal_gate", "fund_balance", "earning_balance", "reinsurance_balance", "explanation_only" ] }, "affected": { "type": "object", "additionalProperties": true, "description": "References to the affected primitive instances." }, "amount_minor": { "type": "integer", "format": "int64", "description": "Exact integer minor units for money components." }, "currency": { "type": "string", "description": "Lowercase ISO-4217 currency when amount_minor is present." }, "ratio_bps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Exact basis-point ratio when the component represents a proportion." }, "effective_start": { "type": "string", "format": "date-time" }, "effective_end": { "type": "string", "format": "date-time" }, "reason_code": { "type": "string", "description": "Tenant-owned reason code or fail-closed code." }, "metadata": { "type": "object", "additionalProperties": true } } }, "ProrationAdjustmentDecision": { "type": "object", "description": "Event-effective proration decision resource.", "required": [ "id", "event_id", "status", "event_type", "proration_intent", "components", "ledger_entry_ids", "explanation_tree_id", "evidence_entry_id", "ruleset" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Proration decision UUID.", "example": "f5430790-ad21-526a-945d-f06736f06e55", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "event_id": { "type": "string", "description": "Triggering event identity in wire form.", "example": "evt_01j9zxkp8wqrm2n4v6t5s3d7f1", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "status": { "type": "string", "enum": [ "posted", "evaluated", "refused" ] }, "event_type": { "type": "string", "description": "Event type resolved from the existing triggering event row." }, "proration_intent": { "type": "string", "description": "Tenant ruleset key used for evaluation." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ProrationAdjustmentComponent" } }, "ledger_entry_ids": { "type": "array", "description": "Ledger entry ids created by financial components; empty for zero-money/refused decisions.", "items": { "type": "string" } }, "explanation_tree_id": { "type": "string", "description": "Durable explanation tree identity in wire form.", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "evidence_entry_id": { "type": "integer", "format": "int64", "description": "governed contract evidence journal entry id for the persisted decision." }, "ruleset": { "type": "object", "additionalProperties": false, "required": [ "ruleset_type", "ruleset_id", "ruleset_version", "resolved_at" ], "properties": { "ruleset_type": { "type": "string", "example": "proration_adjustments" }, "ruleset_id": { "type": "string", "x-axiom-identifier-classification": "ruleset-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 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.45 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.45 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.45 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.45 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.45 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.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } }, "effective_times": { "type": "object", "additionalProperties": false, "required": [ "premium_period_start", "premium_period_end" ], "properties": { "premium_period_start": { "type": "string", "format": "date-time", "description": "Start of the premium period to evaluate." }, "premium_period_end": { "type": "string", "format": "date-time", "description": "End of the premium period to evaluate." }, "cover_start": { "type": "string", "format": "date-time", "description": "Start of the cover-effective interval when different from premium period." }, "cover_end": { "type": "string", "format": "date-time", "description": "End of the cover-effective interval when different from premium period." }, "entitlement_start": { "type": "string", "format": "date-time", "description": "Start of the entitlement interval when applicable." }, "entitlement_end": { "type": "string", "format": "date-time", "description": "End of the entitlement interval when applicable." } } }, "inputs": { "type": "object", "description": "Tenant-owned rule inputs. Shape is validated by the resolved tenant ruleset.", "additionalProperties": true } } }, "ProrationAdjustmentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationAdjustmentDecision" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProrationBalanceResult" } }, "required": [ "data" ], "additionalProperties": true } ] }, "ProrationBalanceResult": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount", "item_count" ], "properties": { "currency": { "type": "string", "description": "Lowercase ISO-4217 currency for money balances." }, "amount": { "type": "string", "description": "Decimal string amount produced by the governed contract balance engine.", "x-axiom-money-classification": "decimal-string-alpha-exception", "x-axiom-money-currency-association": "sibling-currency-field", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "item_count": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "explanation": { "type": "object", "additionalProperties": true } } }, "QueryEvidenceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecord" } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": "string" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "Quote": { "type": "object", "required": [ "quote_id", "product_id", "effective_date", "expiry_date", "underwriting_data", "covers_selected", "pricing_snapshot", "created_at", "valid_until", "actor_type", "actor_id", "actor_original_id" ], "properties": { "quote_id": { "type": "string", "example": "qte-a1b2c3d4", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "product_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "effective_date": { "type": "string", "format": "date-time" }, "expiry_date": { "type": "string", "format": "date-time" }, "underwriting_data": { "type": "object", "additionalProperties": true }, "covers_selected": { "type": "array", "items": { "type": "string" } }, "pricing_snapshot": { "type": "object", "description": "Full premium calculation result snapshot (JSONB)", "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "actor_type": { "type": "string", "description": "Actor type that created the quote (governed contract)", "example": "human" }, "actor_id": { "type": "string", "description": "Actor identifier that created the quote (governed contract)", "x-axiom-identifier-classification": "actor-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "description": "Original actor identifier before delegation (governed contract)", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "comparison_ref": { "type": "string", "description": "Links comparison sets for quote comparison" }, "supersedes_quote_id": { "type": "string", "description": "Quote ID this quote supersedes", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteParty" }, "description": "Party snapshot for bind-time matching" } }, "additionalProperties": false }, "QuoteListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "QuoteParty": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "role": { "type": "string" } }, "additionalProperties": false }, "QuoteResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RecordClaimAuthorisationRequest": { "type": "object", "required": [ "transition_kind", "authorisation_kind", "authorising_actor", "decision_date", "explanation_node_id" ], "properties": { "logical_authorisation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Logical thread id for grant/amend/revoke chains. Generated when omitted.", "x-axiom-identifier-shape": "uuid" }, "transition_kind": { "type": "string", "description": "Sector-neutral transition verb.", "example": "authorisation-granted" }, "authorisation_kind": { "type": "string", "description": "Tenant-keyed authorisation kind.", "example": "pre-auth" }, "authorising_actor": { "type": "string", "format": "uuid", "description": "Party-in-role actor that granted the authorisation." }, "authorised_scope": { "type": "object", "additionalProperties": true, "description": "Typed grant envelope such as procedures, codes, or engagement scope." }, "budget_minor": { "type": "integer", "format": "int64", "nullable": true, "description": "Exact integer minor units for the authorised budget ceiling.", "x-axiom-money-classification": "integer-minor-units-alpha-exception", "x-axiom-money-currency-association": "operation-or-tenant-currency-inherited-alpha", "x-axiom-money-migration-target": "#/components/schemas/Money" }, "budget_currency_code": { "type": "string", "pattern": "^[a-z]{3}$", "nullable": true, "description": "Lowercase ISO-4217 currency code. Present iff budget_minor is present." }, "governing_version_kind": { "type": "string", "nullable": true, "description": "Governing-version discriminator such as catalogue, rule, cover, or engagement-terms." }, "governing_version_row_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Immutable row-id revision of the governing version current at the decision date.", "x-axiom-identifier-shape": "uuid" }, "compliance_kind": { "type": "string", "nullable": true, "description": "Tenant-keyed compliance kind such as accreditation or sanctions-screening." }, "compliance_outcome": { "type": "string", "nullable": true, "enum": [ "clear", "hit", "pending", "unset", "override" ], "description": "Compliance outcome consulted by the payment gate when payment cites this authorisation." }, "compliance_list_version": { "type": "string", "nullable": true, "description": "Tenant-supplied as-was list or standard version." }, "compliance_list_authority": { "type": "string", "nullable": true, "description": "Tenant-keyed list authority such as cms, ofac, ofsi, or eu." }, "decision_date": { "type": "string", "format": "date-time", "description": "Moment the authorisation decision was made." }, "explanation_node_id": { "type": "string", "format": "uuid", "description": "Explanation-node reference for the authorisation decision.", "x-axiom-identifier-shape": "uuid" }, "finding_reference": { "type": "string", "format": "uuid", "nullable": true, "description": "Required by the persistence rule on revoke or withdrawal transitions." } }, "additionalProperties": false }, "RecordClaimAuthorisationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthorisationTransition" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RoleContext": { "type": "object", "required": [ "entity_type", "entity_id" ], "properties": { "entity_type": { "type": "string", "enum": [ "policy", "claim", "organization", "product", "policy_item", "group" ], "description": "The type of entity this role is scoped to. `group` identifies a PartyGroup context while the assignee remains the Party.", "example": "group" }, "entity_id": { "type": "string", "format": "typed-prefix-id", "description": "The identifier of the entity this role is scoped to", "example": "pol_01j9zxkp8wqrm2n4v6t5s3d7f4", "x-axiom-identifier-shape": "typed-prefix" } }, "additionalProperties": false }, "RoleTypeListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartyRoleTypeEntry" }, "example": [ { "code": "policyholder", "display_name": "Policyholder", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true }, { "code": "beneficiary", "display_name": "Beneficiary", "universal": true, "assignable_context_types": [ "policy", "policy_item" ], "requires_attribution": true } ] }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RoleTypeUsageItem": { "type": "object", "required": [ "code", "count" ], "properties": { "code": { "type": "string", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "count": { "type": "integer" } }, "additionalProperties": false }, "RoleTypeUsageListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoleTypeUsageItem" } }, "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RuleAction": { "type": "object", "required": [ "action_type", "target", "value" ], "properties": { "action_type": { "type": "string", "description": "Type of action to execute.\nCommon types: set_field, emit_event, add_loading, apply_discount,\nreject, approve, escalate, notify.\n", "example": "add_loading" }, "target": { "type": "string", "description": "Target field or entity the action applies to", "example": "premium.young_driver_loading" }, "value": { "description": "Value to set, apply, or emit. Type depends on the action_type.", "example": 0.15 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional parameters for the action", "example": { "reason": "Driver under 25 \u2014 young driver loading applied", "loading_type": "percentage" } } }, "additionalProperties": false }, "RuleCondition": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "Dot-notation path to the field being evaluated", "example": "vehicle.year_of_manufacture" }, "operator": { "type": "string", "description": "Comparison operator to apply.\nCommon operators: eq, ne, gt, gte, lt, lte, in, not_in, contains, matches.\n", "example": "gte" }, "value": { "description": "Value to compare against. Type depends on the field and operator.", "example": 2015 }, "logic": { "type": "string", "nullable": true, "description": "Logical connector to the next condition.\n- and: Both this and the next condition must be true\n- or: Either this or the next condition must be true\nIf omitted on the last condition, defaults to implicit AND with the rule expression.\n", "enum": [ "and", "or" ], "example": "and" } }, "additionalProperties": false }, "RuleEvaluationResult": { "type": "object", "required": [ "rule_id", "rule_name", "outcome", "executed_at" ], "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the rule definition", "example": "rule-fraud-score-v2", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_name": { "type": "string", "description": "Human-readable rule name", "example": "Fraud Probability Score" }, "outcome": { "type": "string", "description": "Rule evaluation outcome (e.g. pass, fail, warn, skip)", "example": "pass" }, "value": { "type": "string", "nullable": true, "description": "Rule evaluation output value (type depends on the rule)", "example": "0.12" }, "error": { "type": "string", "nullable": true, "description": "Error message if rule evaluation failed", "example": null }, "executed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was evaluated", "example": "2026-02-18T15:58:00Z" } }, "additionalProperties": false }, "Ruleset": { "type": "object", "required": [ "id", "code", "name", "entity_type", "description", "status", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique ruleset identifier", "example": "7ffab4d3-56e1-548b-a116-a577714722cd", "x-axiom-identifier-shape": "uuid" }, "code": { "type": "string", "description": "Machine-readable code for the ruleset. Used for programmatic reference\nand cross-referencing with product configurations.\n", "example": "motor-comprehensive-v1", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "name": { "type": "string", "description": "Human-readable name for the ruleset", "example": "Motor Vehicle Rating Rules" }, "entity_type": { "type": "string", "enum": [ "claims", "underwriting", "pricing", "claims_assessment", "document_completeness", "discount" ], "description": "The runtime rule lane this ruleset governs. This is not the same closed\nset as platform entity types used on parties, policies, or claims.\n", "example": "pricing" }, "description": { "type": "string", "description": "Detailed description of what this ruleset covers and its purpose", "example": "Validation and pricing rules for comprehensive motor insurance products" }, "status": { "type": "string", "enum": [ "draft", "active", "deprecated" ], "description": "Lifecycle status of the ruleset.\n- draft: Under development, not yet available for evaluation\n- active: Published and available for evaluation in policy/claim workflows\n- deprecated: Superseded by a newer version; retained for as-was auditability\n", "example": "active" }, "version": { "type": "integer", "minimum": 1, "description": "Monotonically increasing version number. Each modification to rules\ncreates a new version, preserving as-was semantics.\n", "example": 3 }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Extensible metadata for the ruleset (e.g. jurisdiction, product line, effective dates)", "example": { "jurisdiction": "US", "product_line": "motor", "effective_from": "2026-01-01" } }, "rules": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BusinessRule" }, "description": "Ordered list of business rules in this ruleset" }, "annotations": { "type": "array", "nullable": true, "description": "governed contract \u2014 per-element human annotations (\"4GL on steroids\"). Each\nentry explains one element of the ruleset for a human (or agent) reader.\n", "items": { "type": "object", "properties": { "element": { "type": "string", "description": "The element annotated (e.g. a CEL term, a limit, a value_type)." }, "meaning": { "type": "string", "description": "Plain-English explanation of what the element means." }, "source_ref": { "type": "string", "description": "Section/page reference into the source document." } }, "additionalProperties": false } }, "source_provenance_id": { "type": "string", "nullable": true, "description": "governed contract \u2014 soft reference to the source_provenance record (source URL,\nSHA-256, publication date, markdown + PDF archive objects, section/page anchors).\n", "x-axiom-identifier-classification": "source-provenance-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the ruleset was created", "example": "2026-01-10T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the ruleset was last updated", "example": "2026-03-01T14:30:00Z" } }, "additionalProperties": false }, "RulesetDeleteRuleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Rule deletion returns the canonical success envelope with null data." } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "overall_passed", "results", "rules_count" ], "properties": { "overall_passed": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RulesetEvaluationResult" } }, "rules_count": { "type": "integer", "minimum": 0, "example": 2 } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetEvaluationResult": { "type": "object", "required": [ "rule_id", "rule_name", "passed", "outcome", "message" ], "properties": { "rule_id": { "type": "string", "example": "0b601f31-c78a-5246-92a7-2ed20988ebfe", "x-axiom-identifier-classification": "rule-reference", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "rule_name": { "type": "string", "example": "Minimum Driver Age Rule" }, "passed": { "type": "boolean", "description": "Whether the rule evaluation passed.", "example": true }, "outcome": { "type": "string", "description": "Runtime evaluation outcome.", "example": "passed" }, "message": { "type": "string", "description": "Empty when the rule succeeded; contains evaluation error detail when available.", "example": "" } }, "additionalProperties": false }, "RulesetListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ruleset" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "data" ], "additionalProperties": true } ] }, "RulesetResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ruleset" } }, "required": [ "data" ], "additionalProperties": true } ] }, "SingleRuleEvaluationResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "passed", "outcome", "message" ], "properties": { "passed": { "type": "boolean", "example": true }, "outcome": { "type": "string", "example": "passed" }, "message": { "type": "string", "example": "" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": true } ] }, "Subprocessor": { "type": "object", "required": [ "subprocessor_id", "vendor_id", "name", "service_scope", "approval_status" ], "properties": { "subprocessor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique subprocessor identifier", "example": "d3216bd6-21dd-572a-8396-9e1444af9bfb", "x-axiom-identifier-shape": "uuid" }, "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Parent vendor this subprocessor operates under", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Legal or trading name of the subprocessor", "example": "AWS EU West 2 London" }, "service_scope": { "type": "string", "description": "Description of the services the subprocessor provides\nto the parent vendor.\n", "example": "Infrastructure hosting and data storage for policy administration" }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "revoked" ], "description": "Approval status of this subprocessor.\n- pending: Awaiting review and approval\n- approved: Approved for data processing\n- revoked: Previously approved, now revoked\n", "example": "approved" }, "approved_by": { "type": "string", "nullable": true, "readOnly": true, "description": "Identifier of the user who approved this subprocessor", "example": "compliance-officer-001" }, "approved_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "ISO 8601 timestamp when approval was granted", "example": "2026-01-20T11:30:00Z" }, "change_reason": { "type": "string", "nullable": true, "description": "Reason for the most recent status change", "example": "Annual subprocessor review completed \u2014 SOC 2 Type II report verified" } }, "additionalProperties": false }, "SubprocessorDataEnvelope": { "type": "object", "description": "JSON:API single-resource response envelope for a subprocessor", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "$ref": "#/components/schemas/Subprocessor" } }, "additionalProperties": false } }, "additionalProperties": false }, "SuccessEnvelope": { "type": "object", "required": [ "data", "status" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Always the literal string 'success' for successful responses. This invariant is established here and must not be overridden by any operation's response schema." }, "data": { "description": "Operation-specific payload. Overridden per-endpoint via allOf composition (e.g. PartyResponse = allOf:[SuccessEnvelope, {data: Party}]). A caller holding a bare SuccessEnvelope-typed reference sees data as unknown/Any \u2014 hold the op-specific composed type (e.g. PartyResponse) to get the typed data." }, "message": { "type": "string", "description": "Optional human-readable message. Present when supplied by the API." }, "meta": { "type": "object", "description": "Optional response metadata (pagination, request echo). Present when supplied by the API.", "additionalProperties": true }, "links": { "type": "object", "description": "Optional hypermedia links. Present when supplied by the API.", "additionalProperties": true }, "telemetry": { "type": "object", "description": "Response telemetry block under the governed contract. Present on every wrapped success response. Contains timing and trace fields (total_ms, handler_ms, idempotency_replayed, trace_id).", "additionalProperties": true } }, "additionalProperties": true }, "UpdatePartyGroupRequest": { "type": "object", "description": "All fields optional; server updates only those supplied.", "properties": { "display_name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "additionalProperties": false }, "UpdatePartyRequest": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Replacement external identifier. If supplied, the effective source_system must be known and valid.", "example": "BRK-000124", "x-axiom-identifier-classification": "tenant-external-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "source_system": { "$ref": "#/components/schemas/PartyExternalIDSourceSystem" }, "attributes": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Updated party-specific data. Merged with existing attributes.", "example": { "email": "maria.new-email@example.com", "phone": "+46701234567" } }, "status": { "$ref": "#/components/schemas/PartyLifecycleStatus" }, "merged_into_party_id": { "type": "string", "format": "typed-prefix-id", "description": "Required when transitioning to status=merged; rejected for non-merged statuses.", "example": "pty_01j9zxkp8wqrm2n4v6t5s3d7f2", "x-axiom-identifier-shape": "typed-prefix" }, "updated_by": { "type": "string", "description": "Identifier of the user or service performing the update", "example": "admin-user-002" } }, "additionalProperties": false }, "UpdateSubprocessorRequest": { "type": "object", "description": "JSON:API envelope for subprocessor update request", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "subprocessors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated subprocessor name" }, "service_scope": { "type": "string", "description": "Updated service scope description" }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "revoked" ], "description": "Updated approval status" }, "change_reason": { "type": "string", "description": "Reason for the status change" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "UpdateVendorRequest": { "type": "object", "description": "JSON:API envelope for vendor update request", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "type": "object", "description": "Partial vendor update. Only provided fields are modified.", "properties": { "purpose": { "type": "string", "description": "Updated business purpose" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Updated vendor classification" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Updated data classification labels" }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Updated vendor status" }, "security_review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "rejected" ], "description": "Updated security review status" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/CreateIntegrationInput" }, "description": "Updated integrations list" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "ValidationRule": { "type": "object", "required": [ "rule_type", "value", "error_message" ], "properties": { "rule_type": { "type": "string", "enum": [ "min", "max", "pattern", "required", "oneof" ], "description": "Type of validation to apply.\n- min: Minimum numeric value\n- max: Maximum numeric value\n- pattern: Regular expression the value must match\n- required: Value must be non-empty\n- oneof: Value must be one of a predefined set\n", "example": "min" }, "value": { "description": "The validation constraint value (type depends on rule_type)", "example": 1 }, "error_message": { "type": "string", "description": "Human-readable error message when validation fails", "example": "Policy term must be at least 1 month" } }, "additionalProperties": false }, "Vendor": { "type": "object", "required": [ "vendor_id", "name", "purpose", "classification", "accessed_data_classes", "status", "created_at", "updated_at" ], "properties": { "vendor_id": { "type": "string", "format": "uuid", "readOnly": true, "description": "Unique vendor identifier", "example": "f9f3f72a-0a08-5807-be2f-69be9dfbe595", "x-axiom-identifier-shape": "uuid" }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional link to a Party record representing this vendor.\nWhen set, the vendor inherits contact and identity data from the Party.\n", "example": "07805e66-69d7-5b42-a978-32729404b560", "x-axiom-identifier-shape": "uuid" }, "name": { "type": "string", "description": "Legal or trading name of the vendor", "example": "CloudSure Technologies (Pty) Ltd" }, "purpose": { "type": "string", "description": "Business purpose for engaging this vendor\n(e.g. claims processing, payment gateway, document storage).\n", "example": "Cloud-based policy administration and document management" }, "classification": { "type": "string", "enum": [ "A", "B", "C", "D", "E" ], "description": "Vendor data-access classification (A-E) under the governed contract.\nHigher letters indicate more restrictive data access.\n", "example": "B" }, "accessed_data_classes": { "type": "array", "items": { "type": "string" }, "description": "Data classification labels for data this vendor can access.\nUsed for POPIA/GDPR compliance tracking.\n", "example": [ "personal_identifiable", "financial", "health" ] }, "status": { "type": "string", "enum": [ "draft", "onboarding", "active", "suspended", "offboarded" ], "description": "Current lifecycle status of the vendor relationship.\n- draft: Initial vendor record created\n- onboarding: Vendor is being onboarded\n- active: Vendor is approved and operational\n- suspended: Vendor temporarily suspended pending investigation\n- offboarded: Vendor relationship has ended; integrations removed\n", "example": "active" }, "integrations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Integration" }, "description": "System integrations associated with this vendor" }, "security_review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "rejected" ], "nullable": true, "description": "Status of the most recent security review.\n- not_required: No security review needed for this vendor\n- pending: Security review is in progress\n- approved: Security review passed\n- rejected: Security review failed\n", "example": "approved" }, "security_review_approved_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "ISO 8601 timestamp when the security review was approved", "example": "2026-02-15T10:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the vendor record was created", "example": "2025-11-01T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "ISO 8601 timestamp when the vendor record was last updated", "example": "2026-03-05T16:20:00Z" } }, "additionalProperties": false }, "VendorDataEnvelope": { "type": "object", "description": "JSON:API single-resource response envelope for a vendor", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "example": "vendors", "x-axiom-coded-value-classification": "tenant-catalogue-type" }, "attributes": { "$ref": "#/components/schemas/Vendor" } }, "additionalProperties": false } }, "additionalProperties": false }, "VerifyEvidenceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerifyEvidenceResult" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "VerifyEvidenceResult": { "type": "object", "required": [ "record_id", "content_hash", "status" ], "properties": { "record_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content_hash": { "type": "string" }, "status": { "type": "string", "enum": [ "VERIFIED", "TAMPERED", "MISSING", "CORRECTED" ] }, "details": { "type": "string" } }, "additionalProperties": false }, "VerifyIntegrityResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrityResult" } } }, "additionalProperties": false }, "archiveObjectDTO": { "type": "object", "description": "Archived-object descriptor returned by the archive service Ingest.\nShape is service-defined; common fields documented below.\n", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Archive object identifier.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "object_uri": { "type": "string", "description": "Canonical storage URI." }, "content_hash": { "type": "string", "description": "Content hash of the stored payload." }, "mime_type": { "type": "string" }, "original_filename": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "biTemporalEntryDTO": { "type": "object", "description": "Wire shape for a single bi-temporal catalogue entry.\n\n**id / catalogue_id typed-prefix note:**\n- On createBiTemporalEntry (POST /entries) responses the server renders\n `id` as `cae_` (typed-prefix via renderCatalogueEntryID) and\n `catalogue_id` as `cat_` (typed-prefix via renderCatalogueID).\n- On supersedeBiTemporalEntry (POST /entries/{logical_entry_id}/supersede)\n responses both fields are emitted as raw UUIDs (no renderer applied).\nCallers MUST tolerate both forms when processing response payloads.\n\n**source_provenance_id typed-prefix note:**\n- createBiTemporalEntry renders `source_provenance_id` as `spv_`.\n- supersedeBiTemporalEntry returns the raw UUID string.\n", "required": [ "id", "logical_entry_id", "catalogue_id", "code", "description", "status", "valid_from", "recorded_from", "created_at" ], "properties": { "id": { "type": "string", "description": "Physical row identifier. Rendered as `cae_` on create responses;\nraw UUID on supersede responses (see schema description above).\n", "example": "cae_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "logical_entry_id": { "type": "string", "format": "uuid", "description": "Stable cross-version UUID that groups all bi-temporal versions of the\nsame logical code. Always a raw UUID regardless of operation.\n", "example": "310cf32d-9203-5f14-9574-38c755ef42fa", "x-axiom-identifier-shape": "uuid" }, "catalogue_id": { "type": "string", "description": "Parent catalogue UUID. Rendered as `cat_` on create responses;\nraw UUID on supersede responses (see schema description above).\n", "example": "cat_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "code": { "type": "string", "description": "The canonical lookup code for this entry (e.g. `J18.9`, `703157`).", "example": "J18.9", "x-axiom-coded-value-classification": "tenant-catalogue-code" }, "description": { "type": "string", "description": "Human-readable description of the entry.", "example": "Pneumonia, unspecified organism" }, "status": { "type": "string", "description": "Lifecycle status of this entry version (e.g. `active`, `retired`).", "example": "active", "x-axiom-coded-value-classification": "tenant-lifecycle-status" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Tenant-defined JSONB attributes for this entry. Shape is catalogue-specific\nand governed by the Catalogue Descriptor's attribute declarations (governed contract).\n" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of the real-world validity window for this entry version (RFC 3339).\n", "example": "2026-01-01T00:00:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "End of the real-world validity window. Omitted when the entry version is\nopen-ended (valid_to IS NULL in storage). Populated after a supersede\noperation closes this version.\n", "example": "2026-12-31T23:59:59Z" }, "recorded_from": { "type": "string", "format": "date-time", "description": "Immutable physical-anchor timestamp (RFC 3339). Set by the persistence-managed records at\nINSERT time; never settable by callers (governed contract recorded_at axis).\n", "example": "2026-01-15T08:00:00Z" }, "source_provenance_id": { "type": "string", "description": "Source-provenance record identifier. Rendered as `spv_` on create\nresponses; raw UUID on supersede responses. Omitted when no provenance\nrecord is linked.\n", "example": "spv_01j1234567890abcdefghijk", "x-axiom-identifier-classification": "mixed-typed-prefix-and-raw-uuid-alpha-exception", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this mixed typed-prefix/raw-UUID wire shape until the owning runtime response contracts converge on one identifier shape." }, "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339).", "example": "2026-01-15T08:00:00Z" } }, "additionalProperties": false }, "biTemporalEntryListResponse": { "type": "object", "x-items-field": "entries", "description": "Envelope for GET /v1/catalogues/{catalogue-ref}/entries list responses.\nKey is `entries` (not `data`) matching the runtime response object{\"entries\": dtos, \"count\": N}\nat runtime source listBiTemporalEntriesHandler.\nx-items-field tells SDK tooling the rows live under `entries`, NOT\n`data`, so consumers do not silently read an empty page. This is an\nAPI 0.1.0 bounded-list exception: `count` only, no page traversal\nparameters and no `has_more`/`next_cursor`, so the reader returns the\none point-in-time page and stops. Use `/entries/history` for\ncursor-paginated full-history traversal.\n", "required": [ "entries", "count" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/biTemporalEntryDTO" }, "description": "Array of matching bi-temporal entry DTOs." }, "count": { "type": "integer", "description": "Total number of entries returned (same as len(entries); not a paged total).", "example": 42 } }, "additionalProperties": false }, "catalogueDTO": { "type": "object", "required": [ "id", "slug", "name", "source", "refresh_frequency", "created_at", "updated_at", "substrate", "has_descriptor" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-assigned UUID (raw UUID, no typed-prefix; runtime source p.ID.String()).", "x-axiom-identifier-shape": "uuid" }, "slug": { "type": "string", "description": "Human-friendly stable identifier used in URL paths (e.g. `icd-10-za`)." }, "name": { "type": "string", "description": "Human-readable display name." }, "source": { "type": "string", "description": "Upstream data authority (e.g. `WHO/DoH-ZA`, `BHF`)." }, "refresh_frequency": { "type": "string", "description": "Declared refresh cadence (e.g. `annual`, `monthly`, `quarterly`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last mutation timestamp (RFC 3339)." }, "substrate": { "type": "string", "enum": [ "bi-temporal" ], "description": "The catalogue's storage substrate. Always `bi-temporal` now that the\nEdition/CatalogueVersion model is retired (governed contract). Surfaced as an\nenum (not a bool) for forward-safety. Lets a client choose its read\npath without probing the retired `GET .../versions` route.\n" }, "has_descriptor": { "type": "boolean", "description": "True when a Catalogue Descriptor (governed contract) is stamped for this\ncatalogue. Pre-resolved via a single batched presence lookup so a\nclient never probes `GET .../descriptor` and reads meaning from a 404.\n" }, "descriptor_id": { "type": "string", "format": "uuid", "description": "The stamped descriptor's row id (raw UUID); omitted when\nhas_descriptor is false.\n", "x-axiom-identifier-shape": "uuid" }, "discarded_at": { "type": "string", "format": "date-time", "description": "Soft-discard timestamp; omitted on live parents." }, "discarded_by": { "type": "string", "description": "Actor identifier that performed the discard; omitted on live parents." }, "discard_reason": { "type": "string", "description": "Human-intelligible discard justification; omitted on live parents." } }, "additionalProperties": false }, "catalogueListResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/catalogueDTO" } }, "meta": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "catalogueSingleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/catalogueDTO" } }, "additionalProperties": false }, "eventReportDTO": { "type": "object", "additionalProperties": true, "properties": { "event_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "event": { "$ref": "#/components/schemas/Event" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/ingestAndLinkResultDTO" } }, "document_errors": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "ingestAndLinkResultDTO": { "type": "object", "description": "Result of ingesting one file and linking it to an event/assertion.", "additionalProperties": true, "properties": { "archive_object_id": { "type": "string", "description": "Archive object identifier for the ingested file.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_filename": { "type": "string" }, "mime_type": { "type": "string" } } }, "jobStatusDTO": { "type": "object", "description": "Async job status.\n", "required": [ "id", "kind", "state", "submitted_at", "attempt", "max_attempts" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Job UUID.", "x-axiom-identifier-shape": "uuid" }, "kind": { "type": "string", "description": "Work type (e.g. `catalogue.ingest`)." }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "dead_letter" ], "description": "Current job state." }, "submitted_at": { "type": "string", "format": "date-time", "description": "Submission timestamp (RFC 3339)." }, "claimed_at": { "type": "string", "format": "date-time", "description": "When a worker claimed the job (RFC 3339). Omitted until claimed." }, "completed_at": { "type": "string", "format": "date-time", "description": "Terminal-state timestamp (RFC 3339). Omitted until terminal." }, "attempt": { "type": "integer", "description": "Current attempt number." }, "max_attempts": { "type": "integer", "description": "Maximum attempts before dead-lettering." }, "correlation_id": { "type": "string", "description": "Correlation id threaded through the job. Omitted when unset.", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "last_error": { "$ref": "#/components/schemas/jobStatusError" }, "error": { "$ref": "#/components/schemas/jobStatusError" }, "progress": { "$ref": "#/components/schemas/jobStatusProgress" } }, "additionalProperties": false }, "jobStatusError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "x-axiom-coded-value-classification": "platform-error-code" }, "message": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": false }, "jobStatusProgress": { "type": "object", "required": [ "completed_units" ], "properties": { "completed_units": { "type": "integer", "format": "int64", "description": "Units of work completed so far." }, "total_units": { "type": "integer", "format": "int64", "description": "Total units of work, when known. Omitted when indeterminate." }, "message": { "type": "string", "description": "Free-text progress message." }, "last_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last progress update (RFC 3339)." } }, "additionalProperties": false }, "jobStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/jobStatusDTO" } }, "additionalProperties": false }, "objectUploadInitiateDTO": { "type": "object", "description": "Presigned-upload coordinates.\n", "required": [ "upload_id", "put_url", "object_uri", "expires_at" ], "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Server-assigned upload identifier, referenced in downstream ingest calls.", "example": "310cf32d-9203-5f14-9574-38c755ef42fa", "x-axiom-identifier-shape": "uuid" }, "put_url": { "type": "string", "description": "Presigned PUT URL \u2014 upload the raw bytes here with HTTP PUT." }, "object_uri": { "type": "string", "description": "Canonical storage URI (managed-object://redacted context/upload_id)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry of the presigned URL (RFC 3339); typically 1 hour from issue." } }, "additionalProperties": false }, "objectUploadInitiateResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/objectUploadInitiateDTO" } }, "additionalProperties": false }, "replacementActor": { "type": "object", "required": [ "actor_type", "actor_id", "actor_original_id" ], "properties": { "actor_type": { "type": "string", "description": "Actor type (e.g. `human`, `service`)." }, "actor_id": { "type": "string", "description": "Actor identifier (typed-prefix wire form).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "actor_original_id": { "type": "string", "description": "Original (pre-merge) actor identifier for audit continuity.", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "replacementAdvanceRequest": { "type": "object", "required": [ "actor", "reason", "occurred_at", "evidence_payload", "version" ], "properties": { "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible justification for the advance." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "evidence_payload": { "type": "object", "additionalProperties": true, "description": "Step-specific evidence required to advance." }, "version": { "type": "integer", "description": "Optimistic-concurrency version of the workflow being advanced." } }, "additionalProperties": false }, "replacementCancelRequest": { "type": "object", "required": [ "actor", "reason", "occurred_at", "version" ], "properties": { "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible cancellation justification." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "version": { "type": "integer", "description": "Optimistic-concurrency version of the workflow being cancelled." } }, "additionalProperties": false }, "replacementDTO": { "type": "object", "description": "Replacement workflow state.\n", "required": [ "id", "policy_id", "existing_policy_ids", "jurisdiction_code", "state", "allowed_transitions", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Replacement workflow id (prp_ typed-prefix).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "policy_id": { "type": "string", "description": "Replacement policy id.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "existing_policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Superseded policy ids." }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code (lowercase ISO 3166-1 alpha-2)." }, "state": { "type": "string", "description": "Current workflow step/state.", "x-axiom-coded-value-classification": "tenant-lifecycle-state" }, "config_pack_version_id": { "type": "string", "description": "Config-pack version governing this workflow's rules.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "step_evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Per-step evidence reference ids." }, "step_timestamps": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "Per-step transition timestamps." }, "transition_history": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ordered transition records." }, "allowed_transitions": { "type": "array", "items": { "type": "string" }, "description": "Transitions permitted from the current state." }, "explanation_tree_id": { "type": "string", "description": "Explanation-tree id for this decision (governed contract). Omitted when unset.", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.45 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "version": { "type": "integer", "description": "Optimistic-concurrency version." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "time_gate_info": { "type": "object", "description": "Present when the next step is time-gated.", "properties": { "step_name": { "type": "string" }, "min_wait_duration": { "type": "string" }, "earliest_advance": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false }, "replacementEvidenceDTO": { "type": "object", "required": [ "replacement_id", "step_evidence", "evidence_order" ], "properties": { "replacement_id": { "type": "string", "format": "uuid", "description": "Replacement workflow UUID.", "x-axiom-identifier-shape": "uuid" }, "step_evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Per-step evidence reference ids." }, "evidence_order": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of step names in evidence-collection order." } }, "additionalProperties": false }, "replacementEvidenceResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/replacementEvidenceDTO" } }, "additionalProperties": false }, "replacementInitiateRequest": { "type": "object", "required": [ "policy_id", "existing_policy_ids", "jurisdiction_code", "actor", "reason", "occurred_at" ], "properties": { "policy_id": { "type": "string", "description": "The replacement policy id (typed-prefix wire form).", "x-axiom-identifier-classification": "typed-prefix-wire-id", "x-axiom-identifier-shape": "typed-prefix" }, "existing_policy_ids": { "type": "array", "items": { "type": "string" }, "description": "Policies being superseded by this replacement." }, "jurisdiction_code": { "type": "string", "description": "ISO 3166-1 alpha-2 jurisdiction code (lowercase)." }, "actor": { "$ref": "#/components/schemas/replacementActor" }, "reason": { "type": "string", "description": "Human-intelligible justification (audit trail)." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Business-event timestamp (RFC 3339)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional caller-supplied metadata." } }, "additionalProperties": false }, "replacementSingleResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/replacementDTO" } }, "additionalProperties": false } }, "responses": { "BadRequest": { "description": "**400 Bad Request**\n\nThe request was malformed or contained invalid parameters.\n\nCommon causes:\n- Missing required parameter\n- Invalid parameter format\n- Invalid JSON syntax\n- Unsupported content type\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_parameter": { "summary": "Missing required parameter", "value": { "errors": [ { "status": "400", "code": "MISSING_PARAMETER", "title": "Bad Request", "detail": "Required parameter 'tenant context' is missing", "source": { "parameter": "tenant context" } } ] } }, "invalid_uuid": { "summary": "Invalid UUID format", "value": { "errors": [ { "status": "400", "code": "INVALID_PARAMETER", "title": "Bad Request", "detail": "Parameter 'id' must be a valid UUID", "source": { "parameter": "id" } } ] } } } } } }, "Conflict": { "description": "**409 Conflict**\n\nThe request conflicts with the current state of the resource.\n\nCommon causes:\n- Attempting to create a duplicate resource\n- Optimistic locking failure (stale version)\n- Invalid state transition\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicate": { "summary": "Duplicate resource", "value": { "errors": [ { "status": "409", "code": "DUPLICATE_RESOURCE", "title": "Conflict", "detail": "A policy with this number already exists" } ] } }, "version_conflict": { "summary": "Version conflict", "value": { "errors": [ { "status": "409", "code": "OPTIMISTIC_LOCK_FAILURE", "title": "Conflict", "detail": "Resource was modified by another request. Please refresh and try again.", "meta": { "current_version": 5, "provided_version": 3 } } ] } } } } } }, "Forbidden": { "description": "**403 Forbidden**\n\nThe authenticated user does not have permission to perform this action.\n\nCommon causes:\n- Insufficient role permissions\n- Accessing another tenant's resource\n- Resource-level access control denial\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_permissions": { "summary": "Insufficient permissions", "value": { "errors": [ { "status": "403", "code": "INSUFFICIENT_PERMISSIONS", "title": "Forbidden", "detail": "You do not have permission to perform this action" } ] } }, "tenant_access": { "summary": "Tenant access denied", "value": { "errors": [ { "status": "403", "code": "TENANT_ACCESS_DENIED", "title": "Forbidden", "detail": "You are not authorized to access this tenant's resources" } ] } } } } } }, "InternalError": { "description": "**500 Server Error**\n\nAn unexpected error occurred. The correlation ID can be used\nfor support inquiries.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "500", "code": "SERVER_ERROR", "title": "Server Error", "detail": "An unexpected error occurred. Please try again later.", "meta": { "correlation_id": "req-abc-123-def-456" } } ] } } } }, "NotFound": { "description": "**404 Not Found**\n\nThe requested resource was not found.\n\nNote: For security, we return 404 instead of 403 when the user\nis not authorized to know whether the resource exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "errors": [ { "status": "404", "code": "RESOURCE_NOT_FOUND", "title": "Not Found", "detail": "The requested policy was not found" } ] } }, "endpoint_not_found": { "summary": "Endpoint not found", "value": { "errors": [ { "status": "404", "code": "ENDPOINT_NOT_FOUND", "title": "Not Found", "detail": "The requested endpoint does not exist" } ] } } } } } }, "ServiceUnavailable": { "description": "**503 Service Unavailable**\n\nThe service is temporarily unavailable. Usually due to\nmaintenance or high load.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "503", "code": "SERVICE_UNAVAILABLE", "title": "Service Unavailable", "detail": "The service is temporarily unavailable. Please try again later.", "help_url": "https://developers.afr-dev.axiom.express/api/reference/0.1.45/errors/SERVICE_UNAVAILABLE/", "meta": { "retry_after": 30 } } ] } } } }, "TooManyRequests": { "description": "**429 Too Many Requests**\n\nRate limit exceeded. Retry after the specified period.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Limit": { "description": "Request limit per time window", "schema": { "type": "integer", "example": 1000 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit resets", "schema": { "type": "integer", "example": 1707307200 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "429", "code": "RATE_LIMITED", "title": "Too Many Requests", "detail": "Rate limit exceeded. Please retry after 60 seconds.", "help_url": "https://developers.afr-dev.axiom.express/api/reference/0.1.45/errors/RATE_LIMITED/", "meta": { "retry_after": 60 } } ] } } } }, "Unauthorized": { "description": "**401 Unauthorized**\n\nAuthentication is required but was not provided or is invalid.\n\nCommon causes:\n- Missing Authorization header\n- Invalid or expired token\n- Malformed credentials\n", "headers": { "WWW-Authenticate": { "description": "Authentication challenge", "schema": { "type": "string", "example": "Bearer realm=\"axiom\", error=\"invalid_token\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_auth": { "summary": "Missing authentication", "value": { "errors": [ { "status": "401", "code": "AUTHENTICATION_REQUIRED", "title": "Unauthorized", "detail": "Authentication is required to access this resource" } ] } }, "expired_token": { "summary": "Expired token", "value": { "errors": [ { "status": "401", "code": "TOKEN_EXPIRED", "title": "Unauthorized", "detail": "The provided authentication token has expired" } ] } } } } } }, "ValidationError": { "description": "**422 Unprocessable Entity**\n\nThe request was well-formed but contained semantic errors.\n\nCommon causes:\n- Field validation failures\n- Business rule violations\n- Invalid state transitions\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "single_field": { "summary": "Single field validation", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'email' must be a valid email address", "source": { "pointer": "/data/attributes/email" } } ] } }, "multiple_fields": { "summary": "Multiple validation errors", "value": { "errors": [ { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'start_date' is required", "source": { "pointer": "/data/attributes/start_date" } }, { "status": "422", "code": "VALIDATION_ERROR", "title": "Validation Error", "detail": "Field 'premium' must be greater than 0", "source": { "pointer": "/data/attributes/premium" } } ] } }, "business_rule": { "summary": "Business rule violation", "value": { "errors": [ { "status": "422", "code": "BUSINESS_RULE_VIOLATION", "title": "Validation Error", "detail": "Policy end date must be after start date" } ] } } } } } } } }, "x-axiom-schema-contract": { "schema_version": "axiom.public-schema-contract.v1", "posture": "classified-alpha-baseline", "component_schema_count": 238, "object_shape": { "closed_object_count": 188, "open_extension_object_count": 163, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 1, "format_constrained_id_count": 110, "classified_id_string_count": 115, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 15, "classified_money_like_count": 0, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 96, "classified_code_string_count": 35, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }