{ "openapi": "3.0.3", "info": { "title": "Axiom API 0.1.1 - Documents And Evidence", "description": "Document output, evidence, archive, upload, and evidence-pack operations.", "version": "0.1.1", "contact": { "name": "Axiom Platform Team", "email": "hello@axiom.express" }, "license": { "name": "Proprietary", "url": "https://axiom.express/license" } }, "servers": [ { "url": "https://api.afr-dev.axiom.express", "description": "Africa developer preview" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Claim", "description": "Claims processing \u2014 submission, assessment, payment, and closure.\nStatus: submitted \u2192 assessing \u2192 assessed \u2192 approved \u2192 paying \u2192 paid \u2192 closed.\nAlso: submitted \u2192 rejected \u2192 closed.\nDeprecated (RFC-8594; Sunset 2026-08-31) in favour of Assertion.\n\nPublic maturity: Developer preview. This surface is available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0.", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." } }, { "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": "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." } } ], "paths": { "/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.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/replacements/{id}/evidence": { "get": { "operationId": "getReplacementEvidence", "summary": "Get replacement evidence", "description": "Returns the evidence collected per step for a replacement workflow.", "tags": [ "Policy" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "$ref": "#/components/parameters/ReplacementIdPath" } ], "responses": { "200": { "description": "Replacement evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/replacementEvidenceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/archive/objects": { "post": { "operationId": "ingestArchiveObject", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/events/{event_id}/documents": { "post": { "operationId": "uploadEventDocuments", "x-axiom-wire-success-profile": "json-api", "summary": "Upload documents to an event", "description": "Multipart upload of one or more files attached to an existing event.\nEvery file part in the form is ingested into the archive and linked to\nthe event.\n", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/CorrelationHeader" }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Event id (typed-prefix wire form)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "One or more file parts (any field names).", "additionalProperties": { "type": "string", "format": "binary" } } } } }, "responses": { "201": { "description": "Documents ingested and linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadEventDocumentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "multipart-form-data", "parse_memory_bytes": 33554432, "numeric_request_byte_limit": 67108864, "file_count_limit": 10, "enforcement": "runtime" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } } ], "requestBody": { "content": { "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-wire-success-profile": "json-api", "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "standard", "scopes": [ "events: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.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/claims/{id}/pdf": { "get": { "operationId": "generateClaimPDF", "summary": "Generate a claim PDF report", "description": "Generate a PDF document summarising the claim, including the event details,\nassessment results, payment information, and workflow history.\n\nThe PDF is generated on demand and returned as a binary response. For large\nclaims with extensive documentation, generation may take several seconds.\n\nThe generated PDF includes:\n- Claim header (claim number, policy number, status)\n- Event details and description\n- Claim items with amounts\n- Assessment summary and notes\n- Payment details (if applicable)\n- Workflow timeline\n\nThis endpoint returns binary PDF data (application/pdf), not a JSON envelope.\n", "tags": [ "Claim" ], "parameters": [ { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)" }, { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Request correlation ID for tracing" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "typed-prefix-id", "x-axiom-identifier-shape": "typed-prefix" }, "description": "Unique claim identifier" } ], "responses": { "200": { "description": "PDF generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded PDF", "schema": { "type": "string", "example": "attachment; filename=\"CLM-2026-00042.pdf\"" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "BearerAuth": [] } ], "x-axiom-public-maturity": { "availability": "developer-preview", "stability": "evolving", "response_profile": "endpoint-specific", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "endpoint-specific", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/evidence": { "post": { "operationId": "createEvidenceRecord", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}": { "get": { "operationId": "getEvidenceRecord", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/query": { "post": { "operationId": "queryEvidence", "x-axiom-wire-success-profile": "json-api", "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/{evidence_id}/integrity-verifications": { "post": { "operationId": "verifyEvidenceIntegrity", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence/verify": { "post": { "operationId": "verifyEvidence", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/assemble": { "post": { "operationId": "assembleEvidencePack", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": true, "read_allowed": false, "write_allowed": false, "agent_invocation": "restricted-mutation", "tenant_context": "required", "idempotency_required": true, "retry_automation": "forbidden-for-mutation", "source": "generated-public-openapi-profile" } } }, "/v1/evidence-packs/{pack_id}": { "get": { "operationId": "getEvidencePack", "x-axiom-wire-success-profile": "json-api", "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": "json-api", "usage": "available", "published": true, "authorisation": "requires-issued-alpha-access-pack", "alpha_access_required": true, "production_ready": false, "note": "Available to admitted alpha consumers when their issued access pack grants authority; breaking changes remain possible before 1.0.0." }, "x-axiom-contract-consistency": { "response_profile": "json-api", "error_profile": "json-api", "pagination_profile": "not-list", "filter_profile": "none" }, "x-axiom-pagination-contract": { "profile": "not-list", "request_parameters": [], "consumer_posture": "not-list" }, "x-axiom-filter-contract": { "profile": "none", "filter_parameters": [] }, "x-axiom-auth-contract": { "bearer": "required", "scope_profile": "none", "scopes": [], "required_permissions": [], "permission_runtime_posture": "alpha-posture", "tenant_context": "required", "tenant_context_authority": "server-minted-X-Tenant-Context", "client_supplied_tenant_id_authority": "forbidden", "failure_order": [ "bearer-authentication", "tenant-context-validation" ] }, "x-axiom-operational-limits": { "upload": { "mode": "not-upload" }, "rate_limit": { "posture": "not-published", "exception": "API 0.1.1 does not publish a per-operation rate-limit commitment." } }, "x-axiom-operation-safety": { "mutation": false, "read_allowed": true, "write_allowed": false, "agent_invocation": "safe-read", "tenant_context": "required", "idempotency_required": false, "retry_automation": "safe-read-policy-required", "source": "generated-public-openapi-profile" } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from authentication service" } }, "parameters": { "CorrelationHeader": { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "x-axiom-identifier-shape": "uuid" }, "description": "Correlation id for request tracing." }, "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Request correlation ID for end-to-end tracing.\nIf not provided, the server generates one automatically.\nThe response always includes this header for support reference.\n", "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "example": "req-abc-123-def-456" }, "ReplacementIdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "description": "Replacement workflow identifier (prp_ typed-prefix).", "example": "prp_01j1234567890abcdefghijk" }, "TenantHeader": { "name": "X-Tenant-Context", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant-context token (TCT) from POST /v1/me/tenant-context (governed contract)." }, "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": { "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 }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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 } ] }, "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 }, "Error": { "type": "object", "required": [ "status", "title" ], "properties": { "status": { "type": "string", "description": "HTTP status code as a string", "example": "422", "x-axiom-coded-value-classification": "platform-http-status-code" }, "code": { "type": "string", "description": "Application-specific error code", "example": "VALIDATION_ERROR", "pattern": "^[A-Z][A-Z0-9_]*$" }, "title": { "type": "string", "description": "Short, human-readable summary of the error", "example": "Validation Error" }, "detail": { "type": "string", "description": "Human-readable explanation of the error", "example": "Field 'policy_number' is required" }, "help_url": { "type": "string", "format": "uri", "description": "Documentation URL for this error code", "example": "https://developers.afr-dev.axiom.express/api/reference/0.1.1/errors/VALIDATION_ERROR/" }, "source": { "$ref": "#/components/schemas/ErrorSource" }, "meta": { "type": "object", "additionalProperties": true, "description": "Additional error metadata" } }, "additionalProperties": false }, "ErrorMeta": { "type": "object", "properties": { "correlation_id": { "type": "string", "description": "Request correlation ID for support reference", "example": "req-abc-123-def-456", "x-axiom-identifier-classification": "correlation-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the error occurred", "example": "2026-02-07T12:00:00Z" }, "request_id": { "type": "string", "description": "Unique request identifier", "example": "req-789-ghi", "x-axiom-identifier-classification": "request-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Error" }, "description": "Array of error objects" }, "meta": { "$ref": "#/components/schemas/ErrorMeta" } }, "additionalProperties": false }, "ErrorSource": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the field that caused the error", "example": "/data/attributes/policy_number" }, "parameter": { "type": "string", "description": "Query parameter that caused the error", "example": "filter[status]" }, "header": { "type": "string", "description": "Header that caused the error", "example": "X-Tenant-Context" } }, "additionalProperties": false }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "policy_object_id": { "type": "string", "x-axiom-identifier-classification": "opaque-resource-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "actor_original_id": { "type": "string", "x-axiom-identifier-classification": "actor-original-id", "x-axiom-identifier-shape": "alpha-exception", "x-axiom-identifier-alpha-exception": "API 0.1.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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 } ] }, "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 } ] }, "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 } ] }, "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 }, "UploadEventDocumentsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ingestAndLinkResultDTO" } } }, "required": [ "data" ], "additionalProperties": true } ] }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "content_hash": { "type": "string" }, "status": { "type": "string", "enum": [ "VERIFIED", "TAMPERED", "MISSING", "CORRECTED" ] }, "details": { "type": "string" } }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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" } } }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "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.1 preserves this identifier as a named alpha/operational exception until the owning runtime contract migrates to a canonical typed-prefix or UUID wire shape." }, "original_filename": { "type": "string" }, "mime_type": { "type": "string" } } }, "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 }, "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 } }, "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" } ] } } } } } }, "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": 30, "object_shape": { "closed_object_count": 22, "open_extension_object_count": 27, "open_object_gap_count": 0, "posture": "closed-or-intentional-open" }, "identifier_shape": { "typed_id_reference_count": 0, "format_constrained_id_count": 10, "classified_id_string_count": 14, "untyped_id_string_count": 0, "posture": "classified-or-constrained" }, "money_shape": { "shared_money_reference_count": 0, "classified_money_like_count": 0, "inline_money_like_count": 0, "posture": "shared-money-or-classified" }, "coded_values": { "enum_string_count": 7, "classified_code_string_count": 2, "unconstrained_code_string_count": 0, "posture": "enum-or-classified-catalogue" } } }