{ "openapi": "3.1.0", "info": { "title": "Fil One Commerce API", "version": "1.0.0" }, "components": { "schemas": {}, "parameters": {}, "securitySchemes": { "experienceSession": { "type": "apiKey", "in": "cookie", "name": "workos-session" } } }, "paths": { "/v1/core/status": { "get": { "tags": [ "core" ], "responses": { "200": { "description": "Core-finance lane status", "content": { "application/json": { "schema": { "type": "object", "properties": { "lane": { "type": "string", "enum": [ "core" ] }, "status": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "details": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "database", "memory", "missing" ] }, "stripeWebhook": { "type": "string", "enum": [ "configured", "missing" ] }, "stripePayment": { "type": "string", "enum": [ "configured", "missing" ] }, "artifactStorage": { "type": "string", "enum": [ "configured", "missing" ] } }, "required": [ "service", "stripeWebhook", "stripePayment", "artifactStorage" ] } }, "required": [ "lane", "status", "details" ] } } } } } } }, "/v1/core/commands/{resource}": { "post": { "tags": [ "core" ], "parameters": [ { "schema": { "type": "string", "enum": [ "accounts", "procurement_profiles", "price_books", "quotes", "orders", "amendments", "commitments", "invoices", "credit_notes", "refunds", "disputes", "deal_registrations", "commissions", "accounting_exports", "marketplace_reconciliations", "reports" ] }, "required": true, "name": "resource", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "minLength": 1, "maxLength": 80 }, "expectedVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "payload": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "id", "action", "payload" ] } } } }, "responses": { "200": { "description": "Versioned core-finance mutation with atomic audit/outbox identifiers", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "id": { "type": "string" }, "resource": { "type": "string", "enum": [ "accounts", "procurement_profiles", "price_books", "quotes", "orders", "amendments", "commitments", "invoices", "credit_notes", "refunds", "disputes", "deal_registrations", "commissions", "accounting_exports", "marketplace_reconciliations", "reports" ] }, "accountId": { "type": "string" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "data": { "type": "object", "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "resource", "rowVersion", "data", "createdAt", "updatedAt" ] }, "auditEventId": { "type": "string" }, "outboxMessageId": { "type": "string" } }, "required": [ "record", "auditEventId", "outboxMessageId" ] } } } }, "403": { "description": "Account or role scope denied" }, "404": { "description": "Resource not found" }, "409": { "description": "Optimistic version or duplicate conflict" } } } }, "/v1/core/records/{resource}": { "get": { "tags": [ "core" ], "parameters": [ { "schema": { "type": "string", "enum": [ "accounts", "procurement_profiles", "price_books", "quotes", "orders", "amendments", "commitments", "invoices", "credit_notes", "refunds", "disputes", "deal_registrations", "commissions", "accounting_exports", "marketplace_reconciliations", "reports" ] }, "required": true, "name": "resource", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Stable cursor page", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "resource": { "type": "string", "enum": [ "accounts", "procurement_profiles", "price_books", "quotes", "orders", "amendments", "commitments", "invoices", "credit_notes", "refunds", "disputes", "deal_registrations", "commissions", "accounting_exports", "marketplace_reconciliations", "reports" ] }, "accountId": { "type": "string" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "data": { "type": "object", "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "resource", "rowVersion", "data", "createdAt", "updatedAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ] } } } }, "403": { "description": "Account or role scope denied" } } } }, "/v1/core/replays/{provider}/{eventId}": { "post": { "tags": [ "core", "operations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "provider", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "eventId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 2000 } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Replay claimed idempotently", "content": { "application/json": { "schema": { "type": "object", "properties": { "replayed": { "type": "boolean" }, "workflowRunId": { "type": "string" } }, "required": [ "replayed", "workflowRunId" ] } } } }, "403": { "description": "Operator or recent-authentication requirement failed" } } } }, "/v1/core/reports/{report}": { "get": { "tags": [ "core", "reports" ], "parameters": [ { "schema": { "type": "string", "enum": [ "revenue_forecast", "capacity_planning", "renewal_churn_exposure", "partner_performance", "funnel_cycle_time", "margin_poc_cost", "arr_mrr", "billing_collections", "commission_settlement", "three_way_tie_out", "weekly_scorecard" ] }, "required": true, "name": "report", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "Current management report, traceable to source records", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "resource": { "type": "string", "enum": [ "accounts", "procurement_profiles", "price_books", "quotes", "orders", "amendments", "commitments", "invoices", "credit_notes", "refunds", "disputes", "deal_registrations", "commissions", "accounting_exports", "marketplace_reconciliations", "reports" ] }, "accountId": { "type": "string" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "data": { "type": "object", "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "resource", "rowVersion", "data", "createdAt", "updatedAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "403": { "description": "Report scope denied" } } } }, "/v1/webhooks/stripe": { "post": { "tags": [ "core", "webhooks" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "stripe-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified event applied or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "503": { "description": "Webhook processing is unavailable or already in progress" } } } }, "/v1/core/payment-sessions": { "post": { "tags": [ "core", "billing" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" } }, "required": [ "accountId", "invoiceId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Stripe-hosted customer payment session; payment truth remains webhook-derived", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "stripe" ] }, "sessionId": { "type": "string", "minLength": 1 }, "invoiceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "requires_customer_action" ] } }, "required": [ "provider", "sessionId", "invoiceId", "url", "status" ] } } } }, "403": { "description": "Billing permission or account scope denied" }, "409": { "description": "Invoice is no longer payable" }, "503": { "description": "Stripe payment session is not configured" } } } }, "/v1/core/artifacts/{kind}/{id}": { "get": { "tags": [ "core", "documents" ], "parameters": [ { "schema": { "type": "string", "enum": [ "agreement_template", "quote", "partner_quote", "order_form" ] }, "required": true, "name": "kind", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Authorized immutable artifact bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Artifact account scope denied" }, "404": { "description": "Artifact not found" }, "503": { "description": "Immutable evidence storage is not configured" } } } }, "/v1/core/payg-offers/simulate": { "post": { "tags": [ "core", "pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terms": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "effectiveFrom": { "type": "string", "format": "date" }, "sourceUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceCheckedAt": { "type": "string", "format": "date-time" }, "sourceDocumentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "owner": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerAcquisition": { "type": "object", "properties": { "paygRequestsEnabled": { "type": "boolean" }, "trialRequestsEnabled": { "type": "boolean" }, "serviceNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "cancellationNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "trialNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "terms": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false } }, "required": [ "paygRequestsEnabled", "trialRequestsEnabled", "serviceNotice", "cancellationNotice", "trialNotice", "terms", "retention" ], "additionalProperties": false }, "payg": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "storageTbMonthMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "monthlyMinimumMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "partialMonthMinimum": { "type": "string", "enum": [ "full", "prorated" ] }, "correctionWindowDays": { "type": "integer", "minimum": 0, "maximum": 3650 }, "aggregation": { "type": "string", "enum": [ "hourly_average_daily_utc" ] }, "egressRateMinor": { "type": "string", "enum": [ "0" ] }, "apiRateMinor": { "type": "string", "enum": [ "0" ] }, "stripeTaxCode": { "type": "string", "minLength": 1, "maxLength": 255 }, "qboIncomeAccount": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "currency", "storageTbMonthMinor", "monthlyMinimumMinor", "partialMonthMinimum", "correctionWindowDays", "aggregation", "egressRateMinor", "apiRateMinor", "stripeTaxCode", "qboIncomeAccount" ], "additionalProperties": false }, "trial": { "type": "object", "properties": { "durationDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "gracePeriodDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "storageLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "cumulativeEgressLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "maximumCounterAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "egressExhaustion": { "type": "string", "enum": [ "disable_all", "block_egress" ] } }, "required": [ "durationDays", "gracePeriodDays", "storageLimitBytes", "cumulativeEgressLimitBytes", "maximumCounterAgeSeconds", "egressExhaustion" ], "additionalProperties": false } }, "required": [ "name", "sku", "region", "version", "effectiveFrom", "sourceUri", "sourceCheckedAt", "sourceDocumentId", "owner", "payg", "trial" ], "additionalProperties": false }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "averageStorageBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "egressBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "apiOperations": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" } }, "required": [ "terms", "month", "averageStorageBytes", "egressBytes", "apiOperations" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Monthly policy simulation with no enrollment or billing effect", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulation": { "type": "boolean", "enum": [ true ] }, "month": { "type": "string" }, "total": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] }, "serviceStartsAt": { "type": "string" }, "serviceEndsAt": { "type": "string" } }, "required": [ "kind", "amount", "serviceStartsAt", "serviceEndsAt" ] } } }, "required": [ "simulation", "month", "total", "lines" ] } } } }, "403": { "description": "Internal finance permission required" } } } }, "/v1/core/payg-offers/trials": { "get": { "tags": [ "core", "trials" ], "responses": { "200": { "description": "Retained lifetime trial claims", "content": { "application/json": { "schema": { "type": "object", "properties": { "trials": { "type": "array", "items": { "nullable": true } } }, "required": [ "trials" ] } } } }, "403": { "description": "Finance access required" }, "503": { "description": "Trial service unavailable" } } }, "post": { "tags": [ "core", "trials" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "claim" ] }, "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "offerVersionId": { "type": "string", "format": "uuid" }, "verificationEvidenceId": { "type": "string", "pattern": "^(dns|registration):[0-9a-f-]{36}$" } }, "required": [ "action", "id", "organizationId", "offerVersionId", "verificationEvidenceId" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "convert" ] }, "trialId": { "type": "string", "format": "uuid" }, "entitlementId": { "type": "string", "format": "uuid" }, "paygEnrollmentId": { "type": "string", "format": "uuid" } }, "required": [ "action", "trialId" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Verified trial claim or confirmed paid conversion", "content": { "application/json": { "schema": { "type": "object", "properties": { "trial": { "nullable": true } } } } } }, "403": { "description": "Finance access required" }, "409": { "description": "Trial eligibility or evidence conflict" }, "503": { "description": "Trial service unavailable" } } } }, "/v1/core/payg-offers/enrollments": { "get": { "tags": [ "core", "billing" ], "responses": { "200": { "description": "Retained PAYG enrollments", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollments": { "type": "array", "items": { "nullable": true } } }, "required": [ "enrollments" ] } } } }, "403": { "description": "Finance access required" }, "503": { "description": "Billing unavailable" } } }, "post": { "tags": [ "core", "billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "enroll" ] }, "id": { "type": "string", "format": "uuid" }, "offerVersionId": { "type": "string", "format": "uuid" }, "binding": { "type": "object", "properties": { "mappingVersionId": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "format": "uuid" }, "filOneOrganizationId": { "type": "string", "minLength": 1 }, "tenantId": { "type": "string", "minLength": 1 }, "entitlementId": { "type": "string", "minLength": 1 }, "sku": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "meters": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "storage_bytes" ] }, { "type": "string", "enum": [ "egress_bytes" ] }, { "type": "string", "enum": [ "api_operations" ] } ] }, "minItems": 3, "maxItems": 3 }, "status": { "type": "string", "enum": [ "active" ] } }, "required": [ "mappingVersionId", "accountId", "filOneOrganizationId", "tenantId", "entitlementId", "sku", "region", "source", "meters", "status" ], "additionalProperties": false }, "bindingEvidenceId": { "type": "string", "minLength": 1 }, "startsAt": { "type": "string", "format": "date-time" }, "billingAuthority": { "type": "string", "enum": [ "fil_one", "clockwork" ] }, "cutoverEvidenceId": { "type": "string", "minLength": 1 } }, "required": [ "action", "id", "offerVersionId", "binding", "bindingEvidenceId", "startsAt", "billingAuthority" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel" ] }, "enrollmentId": { "type": "string", "format": "uuid" }, "serviceEndsAt": { "type": "string", "format": "date-time" }, "evidenceId": { "type": "string", "minLength": 1 } }, "required": [ "action", "enrollmentId", "serviceEndsAt", "evidenceId" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Verified enrollment or confirmed cancellation retained", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollment": { "nullable": true } } } } } }, "403": { "description": "Finance access required" }, "409": { "description": "Verified evidence required" }, "503": { "description": "Billing unavailable" } } } }, "/v1/core/payg-offers/billing-effects": { "get": { "tags": [ "core", "billing" ], "responses": { "200": { "description": "Retained billing deltas awaiting financial materialization", "content": { "application/json": { "schema": { "type": "object", "properties": { "effects": { "type": "array", "items": { "type": "object", "properties": { "idempotencyKey": { "type": "string" }, "kind": { "type": "string" }, "enrollmentId": { "type": "string" }, "accountId": { "type": "string" }, "month": { "type": "string" }, "revision": { "type": "number" }, "amount": { "type": "object", "properties": { "currency": { "type": "string" }, "minor": { "type": "string" } }, "required": [ "currency", "minor" ] } }, "required": [ "idempotencyKey", "kind", "enrollmentId", "accountId", "month", "revision", "amount" ] } } }, "required": [ "effects" ] } } } }, "403": { "description": "Finance access required" }, "503": { "description": "Billing service unavailable" } } }, "post": { "tags": [ "core", "billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "effectKey": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "effectKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Invoice draft retained and queued for provider delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "creditNoteIds": { "type": "array", "items": { "type": "string" } }, "replay": { "type": "boolean" } }, "required": [ "invoiceId", "replay" ] } } } }, "403": { "description": "Finance access required" }, "409": { "description": "Source or tax evidence requires repair" }, "503": { "description": "Billing service unavailable" } } } }, "/v1/core/payg-offers": { "get": { "tags": [ "core", "pricing" ], "responses": { "200": { "description": "Persisted PAYG/trial policy versions; approval alone does not enable sales", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "status": { "type": "string", "enum": [ "draft", "proposed", "approved", "retired" ] }, "terms": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "effectiveFrom": { "type": "string", "format": "date" }, "sourceUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceCheckedAt": { "type": "string", "format": "date-time" }, "sourceDocumentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "owner": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerAcquisition": { "type": "object", "properties": { "paygRequestsEnabled": { "type": "boolean" }, "trialRequestsEnabled": { "type": "boolean" }, "serviceNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "cancellationNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "trialNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "terms": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false } }, "required": [ "paygRequestsEnabled", "trialRequestsEnabled", "serviceNotice", "cancellationNotice", "trialNotice", "terms", "retention" ], "additionalProperties": false }, "payg": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "storageTbMonthMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "monthlyMinimumMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "partialMonthMinimum": { "type": "string", "enum": [ "full", "prorated" ] }, "correctionWindowDays": { "type": "integer", "minimum": 0, "maximum": 3650 }, "aggregation": { "type": "string", "enum": [ "hourly_average_daily_utc" ] }, "egressRateMinor": { "type": "string", "enum": [ "0" ] }, "apiRateMinor": { "type": "string", "enum": [ "0" ] }, "stripeTaxCode": { "type": "string", "minLength": 1, "maxLength": 255 }, "qboIncomeAccount": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "currency", "storageTbMonthMinor", "monthlyMinimumMinor", "partialMonthMinimum", "correctionWindowDays", "aggregation", "egressRateMinor", "apiRateMinor", "stripeTaxCode", "qboIncomeAccount" ], "additionalProperties": false }, "trial": { "type": "object", "properties": { "durationDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "gracePeriodDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "storageLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "cumulativeEgressLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "maximumCounterAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "egressExhaustion": { "type": "string", "enum": [ "disable_all", "block_egress" ] } }, "required": [ "durationDays", "gracePeriodDays", "storageLimitBytes", "cumulativeEgressLimitBytes", "maximumCounterAgeSeconds", "egressExhaustion" ], "additionalProperties": false } }, "required": [ "name", "sku", "region", "version", "effectiveFrom", "sourceUri", "sourceCheckedAt", "sourceDocumentId", "owner", "payg", "trial" ], "additionalProperties": false }, "createdBy": { "type": "string", "format": "uuid" }, "lastEditedBy": { "type": "string", "format": "uuid" }, "proposedBy": { "type": "string", "nullable": true, "format": "uuid" }, "approvedBy": { "type": "string", "nullable": true, "format": "uuid" }, "approvalEvidenceId": { "type": "string", "nullable": true }, "decisionReason": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "rowVersion", "status", "terms", "createdBy", "lastEditedBy", "proposedBy", "approvedBy", "approvalEvidenceId", "decisionReason", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "offers" ] } } } }, "403": { "description": "Internal finance access required" }, "503": { "description": "Policy service unavailable" } } }, "post": { "tags": [ "core", "pricing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create" ] }, "terms": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "effectiveFrom": { "type": "string", "format": "date" }, "sourceUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceCheckedAt": { "type": "string", "format": "date-time" }, "sourceDocumentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "owner": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerAcquisition": { "type": "object", "properties": { "paygRequestsEnabled": { "type": "boolean" }, "trialRequestsEnabled": { "type": "boolean" }, "serviceNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "cancellationNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "trialNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "terms": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false } }, "required": [ "paygRequestsEnabled", "trialRequestsEnabled", "serviceNotice", "cancellationNotice", "trialNotice", "terms", "retention" ], "additionalProperties": false }, "payg": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "storageTbMonthMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "monthlyMinimumMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "partialMonthMinimum": { "type": "string", "enum": [ "full", "prorated" ] }, "correctionWindowDays": { "type": "integer", "minimum": 0, "maximum": 3650 }, "aggregation": { "type": "string", "enum": [ "hourly_average_daily_utc" ] }, "egressRateMinor": { "type": "string", "enum": [ "0" ] }, "apiRateMinor": { "type": "string", "enum": [ "0" ] }, "stripeTaxCode": { "type": "string", "minLength": 1, "maxLength": 255 }, "qboIncomeAccount": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "currency", "storageTbMonthMinor", "monthlyMinimumMinor", "partialMonthMinimum", "correctionWindowDays", "aggregation", "egressRateMinor", "apiRateMinor", "stripeTaxCode", "qboIncomeAccount" ], "additionalProperties": false }, "trial": { "type": "object", "properties": { "durationDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "gracePeriodDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "storageLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "cumulativeEgressLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "maximumCounterAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "egressExhaustion": { "type": "string", "enum": [ "disable_all", "block_egress" ] } }, "required": [ "durationDays", "gracePeriodDays", "storageLimitBytes", "cumulativeEgressLimitBytes", "maximumCounterAgeSeconds", "egressExhaustion" ], "additionalProperties": false } }, "required": [ "name", "sku", "region", "version", "effectiveFrom", "sourceUri", "sourceCheckedAt", "sourceDocumentId", "owner", "payg", "trial" ], "additionalProperties": false } }, "required": [ "action", "terms" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "save" ] }, "id": { "type": "string", "format": "uuid" }, "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "terms": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "effectiveFrom": { "type": "string", "format": "date" }, "sourceUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceCheckedAt": { "type": "string", "format": "date-time" }, "sourceDocumentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "owner": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerAcquisition": { "type": "object", "properties": { "paygRequestsEnabled": { "type": "boolean" }, "trialRequestsEnabled": { "type": "boolean" }, "serviceNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "cancellationNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "trialNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "terms": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false } }, "required": [ "paygRequestsEnabled", "trialRequestsEnabled", "serviceNotice", "cancellationNotice", "trialNotice", "terms", "retention" ], "additionalProperties": false }, "payg": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "storageTbMonthMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "monthlyMinimumMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "partialMonthMinimum": { "type": "string", "enum": [ "full", "prorated" ] }, "correctionWindowDays": { "type": "integer", "minimum": 0, "maximum": 3650 }, "aggregation": { "type": "string", "enum": [ "hourly_average_daily_utc" ] }, "egressRateMinor": { "type": "string", "enum": [ "0" ] }, "apiRateMinor": { "type": "string", "enum": [ "0" ] }, "stripeTaxCode": { "type": "string", "minLength": 1, "maxLength": 255 }, "qboIncomeAccount": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "currency", "storageTbMonthMinor", "monthlyMinimumMinor", "partialMonthMinimum", "correctionWindowDays", "aggregation", "egressRateMinor", "apiRateMinor", "stripeTaxCode", "qboIncomeAccount" ], "additionalProperties": false }, "trial": { "type": "object", "properties": { "durationDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "gracePeriodDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "storageLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "cumulativeEgressLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "maximumCounterAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "egressExhaustion": { "type": "string", "enum": [ "disable_all", "block_egress" ] } }, "required": [ "durationDays", "gracePeriodDays", "storageLimitBytes", "cumulativeEgressLimitBytes", "maximumCounterAgeSeconds", "egressExhaustion" ], "additionalProperties": false } }, "required": [ "name", "sku", "region", "version", "effectiveFrom", "sourceUri", "sourceCheckedAt", "sourceDocumentId", "owner", "payg", "trial" ], "additionalProperties": false } }, "required": [ "action", "id", "expectedRowVersion", "terms" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "propose", "approve", "reject", "retire" ] }, "id": { "type": "string", "format": "uuid" }, "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "reason": { "type": "string", "minLength": 8, "maxLength": 2000 }, "approvalEvidenceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "action", "id", "expectedRowVersion", "reason" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Saved policy version with audited decision", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "status": { "type": "string", "enum": [ "draft", "proposed", "approved", "retired" ] }, "terms": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "effectiveFrom": { "type": "string", "format": "date" }, "sourceUri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sourceCheckedAt": { "type": "string", "format": "date-time" }, "sourceDocumentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "owner": { "type": "string", "minLength": 1, "maxLength": 255 }, "customerAcquisition": { "type": "object", "properties": { "paygRequestsEnabled": { "type": "boolean" }, "trialRequestsEnabled": { "type": "boolean" }, "serviceNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "cancellationNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "trialNotice": { "type": "string", "minLength": 20, "maxLength": 4000 }, "terms": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "uri": { "type": "string", "maxLength": 2048, "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "documentId", "version", "uri", "sha256" ], "additionalProperties": false } }, "required": [ "paygRequestsEnabled", "trialRequestsEnabled", "serviceNotice", "cancellationNotice", "trialNotice", "terms", "retention" ], "additionalProperties": false }, "payg": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "storageTbMonthMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "monthlyMinimumMinor": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "partialMonthMinimum": { "type": "string", "enum": [ "full", "prorated" ] }, "correctionWindowDays": { "type": "integer", "minimum": 0, "maximum": 3650 }, "aggregation": { "type": "string", "enum": [ "hourly_average_daily_utc" ] }, "egressRateMinor": { "type": "string", "enum": [ "0" ] }, "apiRateMinor": { "type": "string", "enum": [ "0" ] }, "stripeTaxCode": { "type": "string", "minLength": 1, "maxLength": 255 }, "qboIncomeAccount": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "currency", "storageTbMonthMinor", "monthlyMinimumMinor", "partialMonthMinimum", "correctionWindowDays", "aggregation", "egressRateMinor", "apiRateMinor", "stripeTaxCode", "qboIncomeAccount" ], "additionalProperties": false }, "trial": { "type": "object", "properties": { "durationDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "gracePeriodDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "storageLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "cumulativeEgressLimitBytes": { "type": "string", "maxLength": 38, "pattern": "^(0|[1-9]\\d*)$" }, "maximumCounterAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "egressExhaustion": { "type": "string", "enum": [ "disable_all", "block_egress" ] } }, "required": [ "durationDays", "gracePeriodDays", "storageLimitBytes", "cumulativeEgressLimitBytes", "maximumCounterAgeSeconds", "egressExhaustion" ], "additionalProperties": false } }, "required": [ "name", "sku", "region", "version", "effectiveFrom", "sourceUri", "sourceCheckedAt", "sourceDocumentId", "owner", "payg", "trial" ], "additionalProperties": false }, "createdBy": { "type": "string", "format": "uuid" }, "lastEditedBy": { "type": "string", "format": "uuid" }, "proposedBy": { "type": "string", "nullable": true, "format": "uuid" }, "approvedBy": { "type": "string", "nullable": true, "format": "uuid" }, "approvalEvidenceId": { "type": "string", "nullable": true }, "decisionReason": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "rowVersion", "status", "terms", "createdBy", "lastEditedBy", "proposedBy", "approvedBy", "approvalEvidenceId", "decisionReason", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Internal finance access and recent authentication required" }, "409": { "description": "Policy state, version, or distinct approver conflict" }, "503": { "description": "Policy service unavailable" } } } }, "/v1/notifications": { "get": { "tags": [ "notifications" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "required": false, "name": "alertKind", "in": "query" }, { "schema": { "type": "string", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Stable cursor page of notification delivery evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "minLength": 1, "maxLength": 40 }, "alertKind": { "type": "string", "minLength": 1, "maxLength": 60 }, "subjectType": { "type": "string", "minLength": 1, "maxLength": 40 }, "subjectId": { "type": "string", "format": "uuid" }, "template": { "type": "string", "minLength": 1, "maxLength": 200 }, "recipients": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "providerMessageId": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "requestedAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "accountId", "channel", "alertKind", "subjectType", "subjectId", "template", "recipients", "status", "providerMessageId", "failureCode", "requestedAt", "deliveredAt" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ] } } } }, "403": { "description": "Account or role scope denied" }, "503": { "description": "Notification delivery adapter is not configured" } } } }, "/v1/notifications/preferences": { "get": { "tags": [ "notifications" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Notification preferences this account has set", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "alertKind": { "type": "string", "minLength": 1, "maxLength": 60 }, "channel": { "type": "string", "minLength": 1, "maxLength": 40 }, "enabled": { "type": "boolean" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "alertKind", "channel", "enabled", "rowVersion", "updatedAt" ] } } }, "required": [ "items" ] } } } }, "403": { "description": "Account or role scope denied" }, "503": { "description": "Notification preference adapter is not configured" } } }, "put": { "tags": [ "notifications" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "alertKind": { "type": "string", "minLength": 1, "maxLength": 60 }, "channel": { "type": "string", "minLength": 1, "maxLength": 40, "default": "email" }, "enabled": { "type": "boolean" } }, "required": [ "accountId", "alertKind", "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Stored notification preference", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "alertKind": { "type": "string", "minLength": 1, "maxLength": 60 }, "channel": { "type": "string", "minLength": 1, "maxLength": 40 }, "enabled": { "type": "boolean" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "alertKind", "channel", "enabled", "rowVersion", "updatedAt" ] } } } }, "403": { "description": "Account or role scope denied" }, "422": { "description": "The alert kind is a contractual or collections notice and cannot be switched off" }, "503": { "description": "Notification preference adapter is not configured" } } } }, "/v1/lifecycle/status": { "get": { "tags": [ "lifecycle" ], "responses": { "200": { "description": "Lifecycle-platform lane mount", "content": { "application/json": { "schema": { "type": "object", "properties": { "lane": { "type": "string", "enum": [ "lifecycle" ] }, "status": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "details": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "database", "missing" ] }, "registration": { "type": "string", "enum": [ "configured", "missing" ] }, "partnerDomainOwnership": { "type": "string", "enum": [ "configured", "missing" ] }, "esign": { "type": "string", "enum": [ "configured", "missing" ] }, "provisioningWebhook": { "type": "string", "enum": [ "configured", "missing" ] }, "marketplaceWebhook": { "type": "string", "enum": [ "configured", "missing" ] }, "supportWebhook": { "type": "string", "enum": [ "configured", "missing" ] }, "evidenceStorage": { "type": "string", "enum": [ "configured", "missing" ] } }, "required": [ "service", "registration", "partnerDomainOwnership", "esign", "provisioningWebhook", "marketplaceWebhook", "supportWebhook", "evidenceStorage" ] } }, "required": [ "lane", "status", "details" ] } } } } } } }, "/v1/lifecycle/registrations": { "post": { "tags": [ "lifecycle", "onboarding" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legalName": { "type": "string", "minLength": 2 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "registeredAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1 }, "line2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "region": { "type": "string" }, "postalCode": { "type": "string", "minLength": 1 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "line1", "city", "postalCode", "country" ] }, "relationshipRoles": { "type": "array", "items": { "type": "string", "enum": [ "direct_client", "partner", "end_client" ] }, "minItems": 1 }, "businessDomain": { "type": "string", "minLength": 3 }, "registrantEmail": { "type": "string", "format": "email" }, "registrationToken": { "type": "string", "minLength": 32 }, "taxIds": { "type": "array", "items": { "type": "object", "properties": { "jurisdiction": { "type": "string", "pattern": "^[A-Z]{2}$" }, "value": { "type": "string", "minLength": 3 } }, "required": [ "jurisdiction", "value" ] }, "maxItems": 20 }, "billingContact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "name", "email" ] }, "apContact": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "name", "email" ] }, "invoiceDeliveryEmail": { "type": "string", "format": "email" } }, "required": [ "legalName", "country", "registeredAddress", "relationshipRoles", "businessDomain", "registrantEmail", "registrationToken", "taxIds", "billingContact", "apContact", "invoiceDeliveryEmail" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/organizations/{organizationId}/invites": { "post": { "tags": [ "lifecycle", "identity" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "organizationId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "billing", "member", "partner_admin", "partner_seller" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "accountId", "email", "role", "expiresAt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/account-selection": { "post": { "tags": [ "lifecycle", "identity" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" } }, "required": [ "accountId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/partners/{accountId}/domains": { "post": { "tags": [ "lifecycle", "identity", "partners" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3 }, "verificationToken": { "type": "string", "minLength": 16 }, "brandName": { "type": "string", "minLength": 1 }, "logoUrl": { "type": "string", "nullable": true, "format": "uri" }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "communicationOwner": { "type": "string", "enum": [ "fil_one", "partner" ] } }, "required": [ "domain", "verificationToken", "brandName", "logoUrl", "primaryColor", "communicationOwner" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/accounts/{accountId}/procurement-profile": { "put": { "tags": [ "lifecycle", "onboarding" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apContact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "name", "email" ] }, "invoiceDeliveryEmail": { "type": "string", "format": "email" }, "poRequired": { "type": "boolean" }, "exemptions": { "type": "array", "items": { "type": "object", "properties": { "jurisdiction": { "type": "string", "minLength": 1 }, "certificateDocumentId": { "type": "string", "format": "uuid" }, "expiresOn": { "type": "string", "nullable": true, "format": "date" } }, "required": [ "jurisdiction", "certificateDocumentId", "expiresOn" ] } }, "supplierDocuments": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "documentId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "documentId" ] } }, "buyerPortalTasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "minLength": 1 }, "ownerId": { "type": "string", "format": "uuid" }, "dueAt": { "type": "string", "format": "date-time" }, "reminderEveryHours": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "taskId", "ownerId", "dueAt", "reminderEveryHours" ] } } }, "required": [ "apContact", "invoiceDeliveryEmail", "poRequired", "exemptions", "supplierDocuments", "buyerPortalTasks" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/agreement-templates": { "post": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "semanticVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }, "jurisdiction": { "type": "string", "minLength": 2 }, "effectiveOn": { "type": "string", "format": "date" }, "canonicalDocumentId": { "type": "string", "format": "uuid" }, "exactText": { "type": "string", "minLength": 1 }, "exactTextHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "executionMode": { "type": "string", "enum": [ "click_through", "counter_signed" ] }, "approvalEvidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "type", "semanticVersion", "jurisdiction", "effectiveOn", "canonicalDocumentId", "exactText", "exactTextHash", "executionMode", "approvalEvidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/agreement-templates/active": { "get": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": true, "name": "type", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 20 }, "required": true, "name": "jurisdiction", "in": "query" } ], "responses": { "200": { "description": "Active approved agreement template with verified exact text", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "semanticVersion": { "type": "string" }, "jurisdiction": { "type": "string" }, "effectiveOn": { "type": "string", "format": "date" }, "canonicalDocumentId": { "type": "string", "format": "uuid" }, "exactText": { "type": "string", "minLength": 1 }, "exactTextHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "executionMode": { "type": "string", "enum": [ "click_through", "counter_signed" ] } }, "required": [ "id", "type", "semanticVersion", "jurisdiction", "effectiveOn", "canonicalDocumentId", "exactText", "exactTextHash", "executionMode" ] } } } }, "403": { "description": "Agreement read permission denied" }, "404": { "description": "Active approved template not found" }, "503": { "description": "Template evidence storage is not configured" } } } }, "/v1/lifecycle/agreements/customer-paper": { "post": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "uploadedDocumentId": { "type": "string", "format": "uuid" }, "negotiationStatus": { "type": "string", "enum": [ "received", "redlining", "agreed" ] }, "jurisdiction": { "type": "string", "minLength": 2 }, "keyTerms": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "accountId", "uploadedDocumentId", "negotiationStatus", "jurisdiction", "keyTerms" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/agreements/click-through": { "post": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "templateId": { "type": "string", "format": "uuid" }, "templateVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }, "exactText": { "type": "string", "minLength": 1 }, "exactTextHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "authorityTitle": { "type": "string", "minLength": 2 }, "authorityAttested": { "type": "boolean", "enum": [ true ] }, "uiContext": { "type": "object", "properties": { "surface": { "type": "string", "minLength": 1 }, "actionLabel": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 2 } }, "required": [ "surface", "actionLabel", "locale" ] }, "previousAgreementId": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "accountId", "templateId", "templateVersion", "exactText", "exactTextHash", "authorityTitle", "authorityAttested", "uiContext", "previousAgreementId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/agreements/envelopes": { "post": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "agreementId": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "signerEmail": { "type": "string", "format": "email" }, "mode": { "type": "string", "enum": [ "redirect", "embedded" ] }, "returnUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "agreementId", "documentId", "signerEmail", "mode", "returnUrl" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/webhooks/esign": { "post": { "tags": [ "lifecycle", "webhooks" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "esign-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified e-sign callback processed or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "503": { "description": "Webhook adapter unavailable or already processing" } } } }, "/v1/webhooks/provisioning": { "post": { "tags": [ "lifecycle", "webhooks", "provisioning" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "provisioning-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified provisioning confirmation processed or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "503": { "description": "Provisioning webhook adapter unavailable or busy" } } } }, "/v1/webhooks/marketplaces/{provider}": { "post": { "tags": [ "lifecycle", "webhooks", "marketplaces" ], "parameters": [ { "schema": { "type": "string", "enum": [ "aws", "azure", "google" ] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "marketplace-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified marketplace entitlement event processed or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "503": { "description": "Marketplace webhook adapter unavailable or busy" } } } }, "/v1/webhooks/support/{provider}": { "post": { "tags": [ "lifecycle", "webhooks", "support" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,39}$" }, "required": true, "name": "provider", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "support-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified support signal metadata recorded or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "422": { "description": "Verified support provider does not match the path" }, "503": { "description": "Support webhook adapter unavailable or busy" } } } }, "/v1/lifecycle/pocs/{pocId}/conversion": { "post": { "tags": [ "lifecycle", "pocs" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "pocId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "quoteId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" } }, "required": [ "accountId", "quoteId", "orderId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/pocs": { "post": { "tags": [ "lifecycle", "pocs" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "partnerAccountId": { "type": "string", "nullable": true, "format": "uuid" }, "workload": { "type": "string", "minLength": 8 }, "buyerUserId": { "type": "string", "format": "uuid" }, "permittedDataClass": { "type": "string", "minLength": 1 }, "successTests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "target": { "type": "string", "minLength": 1 } }, "required": [ "id", "description", "target" ] }, "minItems": 1 }, "capacityCap": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,18})?$" }, "egressCap": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,18})?$" }, "expiresAt": { "type": "string", "format": "date-time" }, "supportOwnerId": { "type": "string", "format": "uuid" } }, "required": [ "accountId", "partnerAccountId", "workload", "buyerUserId", "permittedDataClass", "successTests", "capacityCap", "egressCap", "expiresAt", "supportOwnerId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/pocs/{pocId}/decisions": { "post": { "tags": [ "lifecycle", "pocs", "exceptions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "pocId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "reason": { "type": "string", "minLength": 8 }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "decision", "reason", "evidenceDocumentId" ] } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/provisioning/{commandId}/recover": { "post": { "tags": [ "lifecycle", "provisioning" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "commandId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 8 } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/end-user-terms/acceptances": { "post": { "tags": [ "lifecycle", "agreements" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "templateId": { "type": "string", "format": "uuid" }, "templateVersion": { "type": "string" }, "exactTextHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "uiContext": { "type": "string", "minLength": 1 } }, "required": [ "accountId", "organizationId", "templateId", "templateVersion", "exactTextHash", "uiContext" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/notices": { "post": { "tags": [ "lifecycle", "renewals" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "non_renewal", "termination", "breach_claim", "other" ] }, "servedOn": { "type": "string", "format": "date" }, "evidenceDocumentId": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "portal", "email", "mail", "esign" ] } }, "required": [ "accountId", "orderId", "type", "servedOn", "evidenceDocumentId", "source" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/renewals": { "get": { "tags": [ "lifecycle", "renewals" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "enum": [ "30", "180", "60_90", "all" ], "default": "all" }, "required": false, "name": "window", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "default": "UTC" }, "required": false, "name": "timeZone", "in": "query" } ], "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/renewals/{orderId}/requests": { "post": { "tags": [ "lifecycle", "renewals" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "requestedAction": { "type": "string", "enum": [ "renew", "change_term", "request_change" ] }, "requestedTermMonths": { "type": "integer", "nullable": true, "minimum": 0, "exclusiveMinimum": true } }, "required": [ "accountId", "requestedAction", "requestedTermMonths" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/renewals/{orderId}/declines": { "post": { "tags": [ "lifecycle", "renewals" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1 }, "authorityTitle": { "type": "string", "minLength": 2 }, "authorityAttested": { "type": "boolean", "enum": [ true ] }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "accountId", "reason", "authorityTitle", "authorityAttested", "evidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/terminations": { "post": { "tags": [ "lifecycle", "offboarding" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "customer_request", "non_renewal", "partner_request", "partner_default", "material_breach" ] }, "effectiveAt": { "type": "string", "format": "date-time" }, "retrievalDays": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "partnerAccountId": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "accountId", "orderId", "reason", "effectiveAt", "retrievalDays", "partnerAccountId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/terminations/{terminationId}/approvals": { "post": { "tags": [ "lifecycle", "offboarding" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "terminationId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "reason": { "type": "string", "minLength": 8 }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "decision", "reason", "evidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/exceptions/{caseId}/decisions": { "post": { "tags": [ "lifecycle", "exceptions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "caseId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "reason": { "type": "string", "minLength": 8 }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "decision", "reason", "evidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/novations": { "post": { "tags": [ "lifecycle", "offboarding" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "formerPartnerAccountId": { "type": "string", "format": "uuid" }, "sourceOrderId": { "type": "string", "format": "uuid" }, "newAgreementId": { "type": "string", "format": "uuid" }, "newOrderId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "partner_default", "partner_exit", "agreed_handoff" ] } }, "required": [ "accountId", "formerPartnerAccountId", "sourceOrderId", "newAgreementId", "newOrderId", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/exceptions": { "post": { "tags": [ "lifecycle", "exceptions" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "nullable": true, "format": "uuid" }, "queue": { "type": "string", "enum": [ "pricing", "legal", "credit_collections", "restricted_parties", "disputes", "deal_registration_disputes", "poc_qualification" ] }, "objectType": { "type": "string", "minLength": 1 }, "objectId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 8 }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "accountId", "queue", "objectType", "objectId", "reason", "evidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/accounts/{accountId}/support-signals": { "get": { "tags": [ "lifecycle", "support" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "since", "in": "query" } ], "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/migrations": { "post": { "tags": [ "lifecycle", "migrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executionMode": { "type": "string", "enum": [ "discovery", "rehearsal", "execute" ] }, "sourceSnapshotHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "resumeRunId": { "type": "string", "nullable": true, "format": "uuid" }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "executionMode", "sourceSnapshotHash", "resumeRunId", "batchSize" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/lifecycle/migrations/{runId}/matches/{legacyAccountId}/decision": { "post": { "tags": [ "lifecycle", "migrations", "exceptions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "runId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "legacyAccountId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 255 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "create", "attach", "skip" ] }, "accountId": { "type": "string", "nullable": true, "format": "uuid" }, "reason": { "type": "string", "minLength": 8 }, "evidenceDocumentId": { "type": "string", "format": "uuid" } }, "required": [ "decision", "accountId", "reason", "evidenceDocumentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Lifecycle operation completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "minLength": 1 }, "signingUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "status" ], "additionalProperties": { "nullable": true } } } } }, "403": { "description": "Account, role, MFA, or recent-authentication denial" }, "503": { "description": "Lifecycle persistence adapter is not configured" } } } }, "/v1/system/status": { "get": { "tags": [ "system" ], "responses": { "200": { "description": "Experience/system lane mount", "content": { "application/json": { "schema": { "type": "object", "properties": { "lane": { "type": "string", "enum": [ "system" ] }, "status": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "details": { "type": "object", "properties": { "externalGates": { "type": "string", "enum": [ "configured", "missing" ] }, "activationTestRunner": { "type": "string", "enum": [ "configured", "missing" ] }, "workosWebhook": { "type": "string", "enum": [ "configured", "missing" ] } }, "required": [ "externalGates", "activationTestRunner", "workosWebhook" ] } }, "required": [ "lane", "status", "details" ] } } } } } } }, "/v1/system/external-gates": { "get": { "tags": [ "system", "operations" ], "responses": { "200": { "description": "Internal external-gate activation register", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "gateKey": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "title": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "minLength": 1 }, "inputRequired": { "type": "string", "minLength": 1 }, "affectedFeature": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "configuredStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "effectiveStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "simulatorState": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "simulatorDetails": { "type": "string", "minLength": 1 }, "inputProvenance": { "type": "string", "enum": [ "unverified", "repository_fixture", "live_signed" ] }, "lastActivationTestStatus": { "type": "string", "enum": [ "never", "passed", "failed" ] }, "lastActivationTestAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastActivationTestedBy": { "type": "string", "nullable": true, "minLength": 1 }, "activationEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "reviewOn": { "type": "string", "nullable": true, "format": "date" }, "statusReason": { "type": "string", "minLength": 1 }, "emergencyDisabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "emergencyDisabledBy": { "type": "string", "nullable": true, "minLength": 1 }, "emergencyDisableReason": { "type": "string", "nullable": true, "minLength": 8 }, "emergencyDisableEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "activationAllowed": { "type": "boolean" }, "blockedReasons": { "type": "array", "items": { "type": "string" } }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "gateKey", "title", "owner", "inputRequired", "affectedFeature", "severity", "configuredStatus", "effectiveStatus", "simulatorState", "simulatorDetails", "inputProvenance", "lastActivationTestStatus", "lastActivationTestAt", "lastActivationTestedBy", "activationEvidenceReference", "reviewOn", "statusReason", "emergencyDisabledAt", "emergencyDisabledBy", "emergencyDisableReason", "emergencyDisableEvidenceReference", "activationAllowed", "blockedReasons", "rowVersion", "updatedAt" ], "additionalProperties": false } } }, "required": [ "items" ] } } } }, "403": { "description": "Internal operator permission required" }, "503": { "description": "Persistent external-gate service unavailable" } } } }, "/v1/system/external-gates/{gateKey}": { "put": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "required": true, "name": "gateKey", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "owner": { "type": "string", "minLength": 2, "maxLength": 200 }, "inputRequired": { "type": "string", "minLength": 8, "maxLength": 2000 }, "configuredStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "reviewOn": { "type": "string", "nullable": true, "format": "date" }, "statusReason": { "type": "string", "minLength": 8, "maxLength": 2000 } }, "required": [ "expectedRowVersion", "owner", "inputRequired", "configuredStatus", "reviewOn", "statusReason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "External-gate status updated with activation policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "gateKey": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "title": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "minLength": 1 }, "inputRequired": { "type": "string", "minLength": 1 }, "affectedFeature": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "configuredStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "effectiveStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "simulatorState": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "simulatorDetails": { "type": "string", "minLength": 1 }, "inputProvenance": { "type": "string", "enum": [ "unverified", "repository_fixture", "live_signed" ] }, "lastActivationTestStatus": { "type": "string", "enum": [ "never", "passed", "failed" ] }, "lastActivationTestAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastActivationTestedBy": { "type": "string", "nullable": true, "minLength": 1 }, "activationEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "reviewOn": { "type": "string", "nullable": true, "format": "date" }, "statusReason": { "type": "string", "minLength": 1 }, "emergencyDisabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "emergencyDisabledBy": { "type": "string", "nullable": true, "minLength": 1 }, "emergencyDisableReason": { "type": "string", "nullable": true, "minLength": 8 }, "emergencyDisableEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "activationAllowed": { "type": "boolean" }, "blockedReasons": { "type": "array", "items": { "type": "string" } }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "gateKey", "title", "owner", "inputRequired", "affectedFeature", "severity", "configuredStatus", "effectiveStatus", "simulatorState", "simulatorDetails", "inputProvenance", "lastActivationTestStatus", "lastActivationTestAt", "lastActivationTestedBy", "activationEvidenceReference", "reviewOn", "statusReason", "emergencyDisabledAt", "emergencyDisabledBy", "emergencyDisableReason", "emergencyDisableEvidenceReference", "activationAllowed", "blockedReasons", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "404": { "description": "Gate not found" }, "409": { "description": "Optimistic row-version conflict" }, "422": { "description": "Fail-closed activation policy denied the update" }, "503": { "description": "Persistent external-gate service unavailable" } } } }, "/v1/system/external-gates/{gateKey}/activation-tests": { "post": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "required": true, "name": "gateKey", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "expectedRowVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Runner-derived external-gate activation test recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "gateKey": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "title": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "minLength": 1 }, "inputRequired": { "type": "string", "minLength": 1 }, "affectedFeature": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "configuredStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "effectiveStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "simulatorState": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "simulatorDetails": { "type": "string", "minLength": 1 }, "inputProvenance": { "type": "string", "enum": [ "unverified", "repository_fixture", "live_signed" ] }, "lastActivationTestStatus": { "type": "string", "enum": [ "never", "passed", "failed" ] }, "lastActivationTestAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastActivationTestedBy": { "type": "string", "nullable": true, "minLength": 1 }, "activationEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "reviewOn": { "type": "string", "nullable": true, "format": "date" }, "statusReason": { "type": "string", "minLength": 1 }, "emergencyDisabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "emergencyDisabledBy": { "type": "string", "nullable": true, "minLength": 1 }, "emergencyDisableReason": { "type": "string", "nullable": true, "minLength": 8 }, "emergencyDisableEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "activationAllowed": { "type": "boolean" }, "blockedReasons": { "type": "array", "items": { "type": "string" } }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "gateKey", "title", "owner", "inputRequired", "affectedFeature", "severity", "configuredStatus", "effectiveStatus", "simulatorState", "simulatorDetails", "inputProvenance", "lastActivationTestStatus", "lastActivationTestAt", "lastActivationTestedBy", "activationEvidenceReference", "reviewOn", "statusReason", "emergencyDisabledAt", "emergencyDisabledBy", "emergencyDisableReason", "emergencyDisableEvidenceReference", "activationAllowed", "blockedReasons", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "404": { "description": "Gate not found" }, "409": { "description": "Optimistic row-version conflict" }, "503": { "description": "Activation-test runner or persistence unavailable" } } } }, "/v1/system/external-gates/{gateKey}/emergency-state": { "put": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "required": true, "name": "gateKey", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "disabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 8, "maxLength": 2000 }, "evidenceReference": { "type": "string", "minLength": 8, "maxLength": 512 } }, "required": [ "expectedRowVersion", "disabled", "reason", "evidenceReference" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "External gate emergency disable or restore recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "gateKey": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "title": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "minLength": 1 }, "inputRequired": { "type": "string", "minLength": 1 }, "affectedFeature": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "configuredStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "effectiveStatus": { "type": "string", "enum": [ "blocked", "review", "pending", "active", "not_required" ] }, "simulatorState": { "type": "string", "enum": [ "ready", "degraded", "unavailable" ] }, "simulatorDetails": { "type": "string", "minLength": 1 }, "inputProvenance": { "type": "string", "enum": [ "unverified", "repository_fixture", "live_signed" ] }, "lastActivationTestStatus": { "type": "string", "enum": [ "never", "passed", "failed" ] }, "lastActivationTestAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastActivationTestedBy": { "type": "string", "nullable": true, "minLength": 1 }, "activationEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "reviewOn": { "type": "string", "nullable": true, "format": "date" }, "statusReason": { "type": "string", "minLength": 1 }, "emergencyDisabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "emergencyDisabledBy": { "type": "string", "nullable": true, "minLength": 1 }, "emergencyDisableReason": { "type": "string", "nullable": true, "minLength": 8 }, "emergencyDisableEvidenceReference": { "type": "string", "nullable": true, "minLength": 1 }, "activationAllowed": { "type": "boolean" }, "blockedReasons": { "type": "array", "items": { "type": "string" } }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "gateKey", "title", "owner", "inputRequired", "affectedFeature", "severity", "configuredStatus", "effectiveStatus", "simulatorState", "simulatorDetails", "inputProvenance", "lastActivationTestStatus", "lastActivationTestAt", "lastActivationTestedBy", "activationEvidenceReference", "reviewOn", "statusReason", "emergencyDisabledAt", "emergencyDisabledBy", "emergencyDisableReason", "emergencyDisableEvidenceReference", "activationAllowed", "blockedReasons", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "404": { "description": "Gate not found" }, "409": { "description": "Optimistic row-version conflict" }, "422": { "description": "Emergency control policy denied the update" }, "503": { "description": "Persistent external-gate service unavailable" } } } }, "/v1/system/external-gates/{gateKey}/activation-tasks": { "post": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "required": true, "name": "gateKey", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "taskKey": { "type": "string", "minLength": 8, "maxLength": 255 }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,63}$" } }, "required": [ "expectedRowVersion", "taskKey", "provider" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Durable external-gate activation task accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 255 }, "taskKey": { "type": "string", "minLength": 8, "maxLength": 255 }, "gateKey": { "type": "string", "enum": [ "EXT-ACC-01", "EXT-LEGAL-01", "EXT-COMMERCIAL-01", "EXT-PROVIDER-01", "EXT-PROVISION-01", "EXT-TAX-01", "EXT-DOMAIN-01", "EXT-BRAND-01", "EXT-APPROVERS-01", "EXT-TEARDOWN-01", "EXT-MARKETPLACE-01", "EXT-MIGRATION-01" ] }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,63}$" }, "expectedGateRowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "status": { "type": "string", "enum": [ "queued", "duplicate" ] }, "submittedAt": { "type": "string", "format": "date-time" } }, "required": [ "runId", "taskKey", "gateKey", "provider", "expectedGateRowVersion", "status", "submittedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "404": { "description": "Gate not found" }, "409": { "description": "Optimistic gate-version or idempotency conflict" }, "503": { "description": "Durable activation scheduler unavailable" } } } }, "/v1/system/exception-roster/{rosterEntryId}": { "put": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "rosterEntryId", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRowVersion": { "type": "integer", "minimum": 0 }, "accountId": { "type": "string", "format": "uuid" }, "queue": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "primary", "backup", "escalation" ] }, "active": { "type": "boolean" }, "qualificationEvidenceReference": { "type": "string", "minLength": 8, "maxLength": 512 }, "qualifiedUntil": { "type": "string", "format": "date-time" }, "absentFrom": { "type": "string", "nullable": true, "format": "date-time" }, "absentUntil": { "type": "string", "nullable": true, "format": "date-time" }, "targetMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "expectedRowVersion", "accountId", "queue", "userId", "role", "active", "qualificationEvidenceReference", "qualifiedUntil", "absentFrom", "absentUntil", "targetMinutes", "priority" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing exception-roster assignment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "queue": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "primary", "backup", "escalation" ] }, "active": { "type": "boolean" }, "qualificationEvidenceReference": { "type": "string", "minLength": 1 }, "qualifiedUntil": { "type": "string", "format": "date-time" }, "absentFrom": { "type": "string", "nullable": true, "format": "date-time" }, "absentUntil": { "type": "string", "nullable": true, "format": "date-time" }, "targetMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "accountId", "queue", "userId", "role", "active", "qualificationEvidenceReference", "qualifiedUntil", "absentFrom", "absentUntil", "targetMinutes", "priority", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "201": { "description": "Exception-roster assignment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "queue": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "primary", "backup", "escalation" ] }, "active": { "type": "boolean" }, "qualificationEvidenceReference": { "type": "string", "minLength": 1 }, "qualifiedUntil": { "type": "string", "format": "date-time" }, "absentFrom": { "type": "string", "nullable": true, "format": "date-time" }, "absentUntil": { "type": "string", "nullable": true, "format": "date-time" }, "targetMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "accountId", "queue", "userId", "role", "active", "qualificationEvidenceReference", "qualifiedUntil", "absentFrom", "absentUntil", "targetMinutes", "priority", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "409": { "description": "Optimistic row-version conflict" }, "422": { "description": "Roster eligibility or assignment policy failed" }, "503": { "description": "Persistent exception-roster service unavailable" } } } }, "/v1/system/exception-cases/{caseId}/reassign": { "post": { "tags": [ "system", "operations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "caseId", "in": "path" }, { "schema": { "type": "string", "minLength": 8 }, "required": true, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedBy": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 8, "maxLength": 2000 } }, "required": [ "requestedBy", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Open exception case reassigned from the persisted roster", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "queue": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" }, "status": { "type": "string", "minLength": 1 }, "ownerUserId": { "type": "string", "format": "uuid" }, "backupUserId": { "type": "string", "nullable": true, "format": "uuid" }, "targetAt": { "type": "string", "format": "date-time" }, "rowVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "accountId", "queue", "status", "ownerUserId", "backupUserId", "targetAt", "rowVersion", "updatedAt" ], "additionalProperties": false } } } }, "403": { "description": "Operator permission or recent authentication failed" }, "404": { "description": "Exception case not found" }, "409": { "description": "Optimistic reassignment conflict" }, "422": { "description": "Roster or open-case policy denied reassignment" }, "503": { "description": "Persistent exception-roster service unavailable" } } } }, "/v1/webhooks/workos": { "post": { "tags": [ "system", "webhooks" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "workos-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true } } } }, "responses": { "200": { "description": "Verified WorkOS event accepted or deduplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processed", "duplicate" ] } }, "required": [ "status" ] } } } }, "503": { "description": "Webhook adapter is not configured" } } } }, "/api/experience/projections/{audience}/{channel}": { "get": { "operationId": "listExperienceProjections", "summary": "List authoritative portal projections", "tags": [ "Experience projections" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "path", "name": "audience", "required": true, "schema": { "type": "string", "enum": [ "customer", "partner", "internal" ] } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] } }, { "in": "query", "name": "accountId", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Authorized projection page", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor", "generatedAt", "freshnessSeconds" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "recordKey", "aggregateType", "aggregateId", "accountId", "audience", "channel", "version", "sourceUpdatedAt", "projectedAt", "stale", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "recordKey": { "type": "string", "minLength": 1 }, "aggregateType": { "type": "string", "minLength": 1 }, "aggregateId": { "type": "string", "format": "uuid" }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "channel": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] }, "version": { "type": "integer", "minimum": 1 }, "sourceUpdatedAt": { "type": "string", "format": "date-time" }, "projectedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } }, "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "generatedAt": { "type": "string", "format": "date-time" }, "freshnessSeconds": { "type": "integer", "minimum": 0 } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "422": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/projections/{audience}/{channel}/{recordKey}": { "get": { "operationId": "readExperienceProjection", "summary": "Read one authoritative portal projection", "tags": [ "Experience projections" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "path", "name": "audience", "required": true, "schema": { "type": "string", "enum": [ "customer", "partner", "internal" ] } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] } }, { "in": "path", "name": "recordKey", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "accountId", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorized projection record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "recordKey", "aggregateType", "aggregateId", "accountId", "audience", "channel", "version", "sourceUpdatedAt", "projectedAt", "stale", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "recordKey": { "type": "string", "minLength": 1 }, "aggregateType": { "type": "string", "minLength": 1 }, "aggregateId": { "type": "string", "format": "uuid" }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "channel": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] }, "version": { "type": "integer", "minimum": 1 }, "sourceUpdatedAt": { "type": "string", "format": "date-time" }, "projectedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/projections/{audience}/{channel}/{recordKey}/actions": { "post": { "operationId": "createExperienceProjectionAction", "summary": "Queue a version-bound authoritative portal command", "tags": [ "Experience projections" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "header", "name": "x-csrf-token", "required": true, "schema": { "type": "string", "minLength": 32 } }, { "in": "header", "name": "idempotency-key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255 } }, { "in": "path", "name": "audience", "required": true, "schema": { "type": "string", "enum": [ "customer", "partner", "internal" ] } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] } }, { "in": "path", "name": "recordKey", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "accountId", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "projectionId", "action", "expectedVersion", "payload" ], "properties": { "projectionId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,79}$" }, "expectedVersion": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Durable projection action receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "projectionId", "aggregateType", "aggregateId", "action", "expectedVersion", "status", "resultReference", "resultCode", "authoritativeVersion", "commandReplayed", "createdAt", "completedAt", "auditEventId", "outboxMessageId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "projectionId": { "type": "string", "format": "uuid" }, "aggregateType": { "type": "string", "minLength": 1 }, "aggregateId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,79}$" }, "expectedVersion": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "queued", "applied", "rejected", "failed" ] }, "resultReference": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "resultCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "authoritativeVersion": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "commandReplayed": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Null while queued and for migrated LEGACY_ terminal outcomes whose original command replay truth is unknowable." }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "auditEventId": { "type": "string", "format": "uuid" }, "outboxMessageId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "422": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/projections/{audience}/{channel}/{recordKey}/actions/{actionRequestId}": { "get": { "operationId": "readExperienceProjectionActionReceipt", "summary": "Read an actor-scoped portal action receipt", "tags": [ "Experience projections" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "path", "name": "audience", "required": true, "schema": { "type": "string", "enum": [ "customer", "partner", "internal" ] } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string", "enum": [ "dashboard", "agreements", "quotes", "orders", "services", "pocs", "billing", "amendments", "procurement", "users", "marketplace", "support", "portfolio", "registrations", "disputes", "commissions", "renewals", "sandboxes", "brand", "queues", "approvals", "collections", "provisioning", "reports" ] } }, { "in": "path", "name": "recordKey", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "in": "path", "name": "actionRequestId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "accountId", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Queued or terminal projection action receipt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "projectionId", "aggregateType", "aggregateId", "action", "expectedVersion", "status", "resultReference", "resultCode", "authoritativeVersion", "commandReplayed", "createdAt", "completedAt", "auditEventId", "outboxMessageId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "projectionId": { "type": "string", "format": "uuid" }, "aggregateType": { "type": "string", "minLength": 1 }, "aggregateId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,79}$" }, "expectedVersion": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "queued", "applied", "rejected", "failed" ] }, "resultReference": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "resultCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "authoritativeVersion": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "commandReplayed": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Null while queued and for migrated LEGACY_ terminal outcomes whose original command replay truth is unknowable." }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "auditEventId": { "type": "string", "format": "uuid" }, "outboxMessageId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/artifacts/render-requests": { "post": { "operationId": "createArtifactRenderRequest", "summary": "Resolve authoritative persisted truth for an artifact render", "description": "Accepts only artifact identity, optimistic source version, and audience scope. Document facts are resolved server-side from persisted records.", "tags": [ "Experience artifacts" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "header", "name": "x-csrf-token", "required": true, "schema": { "type": "string", "minLength": 32 } }, { "in": "header", "name": "idempotency-key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kind", "subjectId", "expectedVersion", "audience" ], "properties": { "kind": { "type": "string", "enum": [ "direct_quote", "partner_transfer_quote", "partner_resale_quote", "order_form", "amendment", "poc_summary", "poc_final_report", "invoice_companion", "receipt", "commission_statement", "renewal_confirmation", "decline_confirmation", "deletion_certificate", "reconciliation_report", "report_export" ] }, "subjectId": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } } } } } }, "responses": { "201": { "description": "Authoritative render request created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "accountId", "audience", "audienceAccountId", "subjectType", "subjectId", "kind", "sourceHash", "sourceVersion", "retainUntil", "status", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "audienceAccountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "subjectType": { "type": "string", "minLength": 1, "maxLength": 80 }, "subjectId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "direct_quote", "partner_transfer_quote", "partner_resale_quote", "order_form", "amendment", "poc_summary", "poc_final_report", "invoice_companion", "receipt", "commission_statement", "renewal_confirmation", "decline_confirmation", "deletion_certificate", "reconciliation_report", "report_export" ] }, "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sourceVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "retainUntil": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "rendering", "stored", "failed" ] }, "version": { "type": "integer", "minimum": 1 } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "422": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/artifacts/render-requests/{requestId}": { "post": { "operationId": "renderArtifactRequest", "summary": "Render, redrive when failed, and immutably store an authoritative artifact request", "tags": [ "Experience artifacts" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "header", "name": "x-csrf-token", "required": true, "schema": { "type": "string", "minLength": 32 } }, { "in": "header", "name": "idempotency-key", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 255 } }, { "in": "path", "name": "requestId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Immutable PDF representation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "subjectType", "subjectId", "accountId", "audience", "audienceAccountId", "documentId", "version", "sourceHash", "contentHash", "mimeType", "byteLength", "filename", "retainUntil", "createdAt", "downloadHref" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "direct_quote", "partner_transfer_quote", "partner_resale_quote", "order_form", "amendment", "poc_summary", "poc_final_report", "invoice_companion", "receipt", "commission_statement", "renewal_confirmation", "decline_confirmation", "deletion_certificate", "reconciliation_report", "report_export" ] }, "subjectType": { "type": "string", "minLength": 1, "maxLength": 80 }, "subjectId": { "type": "string", "format": "uuid" }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "audienceAccountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "documentId": { "type": "string", "format": "uuid" }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mimeType": { "type": "string", "const": "application/pdf" }, "byteLength": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "filename": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,159}\\.pdf$" }, "retainUntil": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "downloadHref": { "type": "string", "pattern": "^/api/experience/artifacts/" } } } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "422": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "502": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/experience/artifacts/{kind}/{artifactId}": { "get": { "operationId": "readExperienceArtifact", "summary": "Read metadata or download verified immutable PDF bytes", "tags": [ "Experience artifacts" ], "security": [ { "experienceSession": [] } ], "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "type": "string", "enum": [ "direct_quote", "partner_transfer_quote", "partner_resale_quote", "order_form", "amendment", "poc_summary", "poc_final_report", "invoice_companion", "receipt", "commission_statement", "renewal_confirmation", "decline_confirmation", "deletion_certificate", "reconciliation_report", "report_export" ] } }, { "in": "path", "name": "artifactId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "representation", "required": false, "description": "Return public metadata as JSON; omit to download verified PDF bytes.", "schema": { "type": "string", "enum": [ "json" ] } } ], "responses": { "200": { "description": "Public artifact metadata or verified immutable PDF", "headers": { "Content-Length": { "description": "Present for a binary PDF response.", "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "Content-Disposition": { "description": "Safe attachment filename for a binary PDF response.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Prevents storage of private artifact bytes.", "schema": { "type": "string", "enum": [ "private, no-store" ] } }, "X-Content-Type-Options": { "schema": { "type": "string", "enum": [ "nosniff" ] } }, "x-content-sha256": { "description": "Present for a binary PDF response.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "subjectType", "subjectId", "accountId", "audience", "audienceAccountId", "documentId", "version", "sourceHash", "contentHash", "mimeType", "byteLength", "filename", "retainUntil", "createdAt", "downloadHref" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "direct_quote", "partner_transfer_quote", "partner_resale_quote", "order_form", "amendment", "poc_summary", "poc_final_report", "invoice_companion", "receipt", "commission_statement", "renewal_confirmation", "decline_confirmation", "deletion_certificate", "reconciliation_report", "report_export" ] }, "subjectType": { "type": "string", "minLength": 1, "maxLength": 80 }, "subjectId": { "type": "string", "format": "uuid" }, "accountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "customer", "partner", "internal" ] }, "audienceAccountId": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "documentId": { "type": "string", "format": "uuid" }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mimeType": { "type": "string", "const": "application/pdf" }, "byteLength": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "filename": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,159}\\.pdf$" }, "retainUntil": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "downloadHref": { "type": "string", "pattern": "^/api/experience/artifacts/" } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "422": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "502": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Problem details response", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } } } }