{ "openapi": "3.1.0", "info": { "title": "vsmBooking API", "version": "0.1.0", "description": "Human-maintained OpenAPI companion for the current logical V1/Public endpoint surface. docs/api/API.md remains canonical for auth, side effects, examples, and release notes." }, "servers": [ { "url": "https://booking.vossmedien.de" }, { "url": "http://localhost:3002" } ], "paths": { "/api/health": { "get": { "summary": "Basic process health", "tags": [ "Health" ], "responses": { "200": { "description": "Basic process health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeHealthEnvelope" } } } } }, "operationId": "getApiHealth", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/health/ready": { "get": { "summary": "Runtime readiness; detailed dependency data requires internal secret in production", "tags": [ "Health" ], "responses": { "200": { "description": "Ready or degraded dependency status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeReadinessEnvelope" } } } }, "503": { "description": "Blocked strict dependency status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeReadinessEnvelope" } } } } }, "operationId": "getApiHealthReady", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/up": { "get": { "summary": "Minimal public uptime endpoint", "tags": [ "Health" ], "responses": { "200": { "description": "Minimal ready or degraded uptime status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeUptimeResult" } } } }, "503": { "description": "Minimal blocked uptime status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeUptimeResult" } } } } }, "operationId": "getUp", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/embed.js": { "get": { "summary": "Customer website Web Component bundle", "tags": [ "Embed" ], "responses": { "200": { "description": "Customer-site Web Component bundle", "content": { "application/javascript": { "schema": { "$ref": "#/components/schemas/EdgeEmbedScriptSource" } } } } }, "operationId": "getEmbedJs", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/openapi/v1.json": { "get": { "summary": "Download the versioned vsmBooking OpenAPI companion", "tags": [ "Developer" ], "responses": { "200": { "description": "Versioned OpenAPI 3.1 JSON document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeOpenApiDocument" } } } }, "304": { "description": "ETag matched; response body omitted" } }, "operationId": "getOpenapiV1Json", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/auth/oauth/providers": { "get": { "summary": "List configured OAuth login providers", "tags": [ "Auth" ], "responses": { "200": { "description": "Public Google and Apple OAuth configuration state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthProviderInventoryEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Public application origin is invalid", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Public application origin is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AuthOauthProviders", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/v1/auth/oauth/accounts": { "get": { "summary": "List linked OAuth accounts", "tags": [ "Auth" ], "responses": { "200": { "description": "Linked OAuth accounts for the browser user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthAccountInventoryEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Persistent OAuth storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Persistent OAuth storage is unavailable" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AuthOauthAccounts", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/oauth/accounts/{provider}": { "delete": { "summary": "Unlink an OAuth account", "tags": [ "Auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } } ], "responses": { "200": { "description": "Unlinked an owned Google or Apple identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthUnlinkEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Linked provider identity was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Identity is the user's last remaining login method", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Linked provider identity was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Identity is the user's last remaining login method" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-identity-unlink", "description": "Deletes the selected owned provider identity." }, { "kind": "security-audit", "description": "Appends an immutable OAuth unlink event." } ] }, "operationId": "deleteApiV1AuthOauthAccountsByProvider", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/oauth/mfa": { "post": { "summary": "Complete MFA after OAuth identity verification", "tags": [ "Auth" ], "responses": { "200": { "description": "OAuth-authenticated browser session after MFA", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_session cookie when a session is issued; MFA challenge responses do not set it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaChallengeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "OAuth MFA cookie or second factor is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaCodeInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "OAuth MFA cookie or second factor is invalid" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mfa-challenge-consume", "description": "Atomically consumes the OAuth-bound challenge and second factor." }, { "kind": "session-issue", "description": "Creates a server session and clears the OAuth MFA cookie." } ] }, "operationId": "postApiV1AuthOauthMfa", "security": [ { "oauthMfaChallenge": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "oauthMfaChallenge", "allowedPrincipals": [ "oauth-mfa-challenge" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_oauth_mfa" } } }, "/api/v1/auth/oauth/link-requests/{token}": { "get": { "summary": "Read an owned pending OAuth link request", "tags": [ "Auth" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 512 } } ], "responses": { "200": { "description": "Pending owned OAuth link confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthLinkRequestEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Owned pending request is invalid or expired", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Owned pending request is invalid or expired" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AuthOauthLinkRequestsByToken", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/oauth/link-requests/{token}/confirm": { "post": { "summary": "Confirm an owned pending OAuth link request", "tags": [ "Auth" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 512 } } ], "responses": { "200": { "description": "Confirmed and linked OAuth identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthAccountEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Owned pending request is invalid or expired", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Provider identity is already linked", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Owned pending request is invalid or expired" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Provider identity is already linked" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-identity-link", "description": "Atomically consumes the request and stores the identity." }, { "kind": "security-audit", "description": "Appends an immutable OAuth linked event." } ] }, "operationId": "postApiV1AuthOauthLinkRequestsByTokenConfirm", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/oauth/link-requests/{token}/reject": { "post": { "summary": "Reject an owned pending OAuth link request", "tags": [ "Auth" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 512 } } ], "responses": { "200": { "description": "Rejected an owned OAuth link confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOAuthRejectEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Owned pending request is invalid or expired", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Owned pending request is invalid or expired" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-link-reject", "description": "Atomically rejects the pending link request." }, { "kind": "security-audit", "description": "Appends an immutable OAuth rejection event." } ] }, "operationId": "postApiV1AuthOauthLinkRequestsByTokenReject", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/oauth/{provider}/start": { "get": { "summary": "Start OAuth login or account linking", "tags": [ "Auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } }, { "name": "intent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "login", "link" ], "default": "login" } }, { "name": "redirect", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "307": { "description": "Redirect to the configured provider authorization endpoint", "headers": { "Location": { "description": "Provider authorization URL", "schema": { "type": "string", "format": "uri" } } } }, "401": { "description": "Link intent requires an authenticated browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Provider or intent is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "OAuth provider or encrypted flow storage is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AuthOauthByProviderStart", "security": [ {}, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "optionalSession", "allowedPrincipals": [ "public", "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Link intent requires an authenticated browser session" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "OAuth provider or encrypted flow storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-flow-create", "description": "Persists one bounded encrypted OAuth flow and redirects to the configured provider." } ] } } }, "/api/v1/auth/oauth/{provider}/callback": { "get": { "summary": "Complete a query-mode OAuth callback", "tags": [ "Auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "303": { "description": "Redirect to login, dashboard, security confirmation, or an OAuth-safe error state", "headers": { "Location": { "description": "Same-origin post-callback destination", "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "description": "May issue a session cookie or short-lived OAuth MFA cookie", "schema": { "type": "string" } } } } }, "operationId": "getApiV1AuthOauthByProviderCallback", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-flow-consume", "description": "Consumes the one-time OAuth flow and reduces provider success or failure to a same-origin redirect." }, { "kind": "oauth-session-or-link", "description": "May issue a session/MFA challenge or create an owned link confirmation after provider verification.", "conditional": true } ] } }, "post": { "summary": "Complete a form-post OAuth callback", "tags": [ "Auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "maxLength": 512 }, "code": { "type": "string", "maxLength": 4096 }, "error": { "type": "string", "maxLength": 160 }, "user": { "type": "string", "maxLength": 16000 } } } } } }, "responses": { "303": { "description": "Redirect to login, dashboard, security confirmation, or an OAuth-safe error state", "headers": { "Location": { "description": "Same-origin post-callback destination", "schema": { "type": "string", "format": "uri" } }, "Set-Cookie": { "description": "May issue a session cookie or short-lived OAuth MFA cookie", "schema": { "type": "string" } } } }, "413": { "description": "Callback form exceeds the bounded payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthOauthByProviderCallback", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "oauth-flow-consume", "description": "Consumes the one-time OAuth flow and reduces provider success or failure to a same-origin redirect." }, { "kind": "oauth-session-or-link", "description": "May issue a session/MFA challenge or create an owned link confirmation after provider verification.", "conditional": true } ] } } }, "/api/v1/auth/register": { "post": { "summary": "Request registration; account is created only after email confirmation", "tags": [ "Auth" ], "responses": { "202": { "description": "Neutral acceptance; the same answer for new and already registered addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRegistrationRequestEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Public registration is disabled", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested tenant slug is already taken", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthRegister", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRegisterInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Public registration is disabled" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested tenant slug is already taken" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "pending-registration", "description": "For a new address, stores a single-use confirmation (password as scrypt hash, link as SHA-256 hash) that expires after 24 hours and replaces older ones.", "conditional": true }, { "kind": "mail-queue", "description": "Queues a confirmation link for a new address or a sign-in notice for an existing account." } ] } } }, "/api/v1/auth/register/confirm": { "post": { "summary": "Confirm registration, create user and first tenant, issue session", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenInput" } } } }, "responses": { "201": { "description": "Created user, optional first tenant, and browser session", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_session cookie when a session is issued; MFA challenge responses do not set it. Sets the HTTP-only vsm_booking_tenant cookie to an authorized joined tenant.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRegisterEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Confirmation token is invalid, expired, superseded, or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Public registration is disabled", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Confirmation token is invalid, expired, superseded, or replayed" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Public registration is disabled" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "pending-registration-consume", "description": "Atomically deletes the pending registration and creates the verified password user." }, { "kind": "tenant-bootstrap", "description": "Creates the optional tenant and joined owner membership.", "conditional": true }, { "kind": "session-issue", "description": "Creates a server session and sets its HTTP-only cookie." } ] }, "operationId": "postApiV1AuthRegisterConfirm", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/v1/auth/login": { "post": { "summary": "Login with email and password", "tags": [ "Auth" ], "responses": { "200": { "description": "Browser session or MFA challenge", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_session cookie when a session is issued; MFA challenge responses do not set it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Credentials are invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthLogin", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Credentials are invalid" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-issue", "description": "Issues a browser session when MFA is not enabled.", "conditional": true }, { "kind": "mfa-challenge-issue", "description": "Issues a five-minute MFA challenge when MFA is enabled.", "conditional": true } ] } } }, "/api/v1/auth/magic-link": { "post": { "summary": "Request passwordless magic-link token", "tags": [ "Auth" ], "responses": { "200": { "description": "Generic magic-link acceptance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMagicLinkEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMagicLink", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMagicLinkInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "magic-link-issue", "description": "Stores a hashed fifteen-minute single-use token." }, { "kind": "mail-queue", "description": "Queues a tenant-scoped magic-link message when configured.", "conditional": true } ] } } }, "/api/v1/auth/magic-link/consume": { "post": { "summary": "Consume passwordless magic-link token and issue session", "tags": [ "Auth" ], "responses": { "200": { "description": "Browser session or MFA challenge", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_session cookie when a session is issued; MFA challenge responses do not set it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMagicLinkConsumeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Magic-link token is invalid, expired, or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMagicLinkConsume", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Magic-link token is invalid, expired, or replayed" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "magic-link-consume", "description": "Atomically consumes the single-use magic-link token." }, { "kind": "session-or-mfa-issue", "description": "Issues either a browser session or an MFA challenge." } ] } } }, "/api/v1/auth/invite/accept": { "post": { "summary": "Accept pending team invitation for authenticated email", "tags": [ "Auth" ], "responses": { "200": { "description": "Consumed invite, tenant, and joined member", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_tenant cookie to an authorized joined tenant.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthInviteAcceptEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Browser session or usable invite token is missing", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Authenticated email does not match the invite", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Invite tenant or pending member no longer exists", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthInviteAccept", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Browser session or usable invite token is missing" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Authenticated email does not match the invite" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Invite tenant or pending member no longer exists" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "invite-consume", "description": "Consumes the single-use team invite token." }, { "kind": "membership-join", "description": "Marks the matching tenant membership as joined." } ] } } }, "/api/v1/auth/tenant": { "post": { "summary": "Select active joined tenant", "tags": [ "Auth" ], "responses": { "200": { "description": "Selected joined tenant context and fresh CSRF token", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_tenant cookie to an authorized joined tenant.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTenantSelectionEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Requested joined tenant is not available to the user", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTenantSelectionInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Requested joined tenant is not available to the user" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "active-tenant-select", "description": "Validates a joined membership and updates the protected active-tenant cookie." } ] }, "operationId": "postApiV1AuthTenant", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/logout": { "post": { "summary": "Revoke current session", "tags": [ "Auth" ], "responses": { "200": { "description": "Revoked current browser session", "headers": { "Set-Cookie": { "description": "Clears the HTTP-only vsm_booking_session cookie. Clears the HTTP-only vsm_booking_tenant cookie.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLogoutEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthLogout", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revoke", "description": "Revokes the current browser session and clears its cookie." } ] } } }, "/api/v1/auth/session": { "get": { "summary": "Read current session and CSRF token", "tags": [ "Auth" ], "responses": { "200": { "description": "Nullable current session and tenant context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCurrentSessionEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AuthSession", "security": [ {}, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "optionalSession", "allowedPrincipals": [ "public", "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-touch", "description": "May update lastSeenAt after the ten-minute touch interval.", "conditional": true } ] } } }, "/api/v1/auth/logout-all": { "post": { "summary": "Revoke every active session for the current user", "tags": [ "Auth" ], "responses": { "200": { "description": "Account-wide session revocation result", "headers": { "Set-Cookie": { "description": "Clears the HTTP-only vsm_booking_session cookie. Clears the HTTP-only vsm_booking_tenant cookie.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLogoutAllEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthLogoutAll", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revoke-all", "description": "Revokes every session for the user and clears the current cookie." } ] } } }, "/api/v1/auth/sessions": { "get": { "summary": "List active browser sessions for the current user", "tags": [ "Auth" ], "responses": { "200": { "description": "Bounded active-session inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionInventoryEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AuthSessions", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-touch", "description": "May update current-session lastSeenAt before listing sessions.", "conditional": true } ] } } }, "/api/v1/auth/session-audit": { "get": { "responses": { "200": { "description": "Bounded immutable account-security audit history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionAuditEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-touch", "description": "May update current-session lastSeenAt before listing audit events.", "conditional": true } ] }, "operationId": "getApiV1AuthSessionAudit", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/auth/sessions/{sessionId}": { "delete": { "summary": "Revoke one active browser session owned by the current user", "tags": [ "Auth" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked owned browser session", "headers": { "Set-Cookie": { "description": "Clears the HTTP-only vsm_booking_session cookie. Clears the HTTP-only vsm_booking_tenant cookie.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionRevocationEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "CSRF token is missing, invalid, or expired", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Active owned session not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1AuthSessionsBySessionId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "CSRF token is missing, invalid, or expired" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Active owned session not found" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revoke", "description": "Revokes the selected owned session." }, { "kind": "session-cookie-clear", "description": "Clears the cookie only when the current session was selected.", "conditional": true } ] } } }, "/api/v1/auth/mfa": { "get": { "summary": "Read the current user's MFA state without secret material", "tags": [ "Auth", "MFA" ], "responses": { "200": { "description": "Sanitized MFA state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaStatusEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or platform-admin role required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AuthMfa", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or platform-admin role required" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-touch", "description": "May update current-session lastSeenAt.", "conditional": true } ] } } }, "/api/v1/auth/mfa/setup": { "post": { "summary": "Start MFA setup and return the one-time TOTP enrollment secret", "tags": [ "Auth", "MFA" ], "responses": { "200": { "description": "Pending TOTP setup secret and authenticator URI", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaSetupEnvelope" } } } }, "401": { "description": "Authenticated browser session required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/platform-admin role or CSRF requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "MFA is already enabled", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "MFA encryption key is missing or invalid", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMfaSetup", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated browser session required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/platform-admin role or CSRF requirement failed" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "MFA is already enabled" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "MFA encryption key is missing or invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mfa-setup-store", "description": "Stores a new pending TOTP secret as AES-256-GCM ciphertext." } ] } } }, "/api/v1/auth/mfa/confirm": { "post": { "summary": "Confirm pending TOTP setup and issue one-time recovery codes", "tags": [ "Auth", "MFA" ], "responses": { "200": { "description": "Enabled MFA and one-time recovery codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaConfirmEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Browser session or TOTP code is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/platform-admin role or CSRF requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Pending MFA setup changed concurrently", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Pending MFA secret cannot be decrypted", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMfaConfirm", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaCodeInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Browser session or TOTP code is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/platform-admin role or CSRF requirement failed" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Pending MFA setup changed concurrently" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Pending MFA secret cannot be decrypted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revoke-others", "description": "Revokes all other sessions before enabling MFA." }, { "kind": "mfa-enable", "description": "Stores the encrypted secret, used TOTP step, and recovery-code hashes." } ] } } }, "/api/v1/auth/mfa/challenge": { "post": { "summary": "Complete a public MFA challenge and issue a browser session", "tags": [ "Auth", "MFA" ], "responses": { "200": { "description": "Authenticated browser session", "headers": { "Set-Cookie": { "description": "Sets the HTTP-only vsm_booking_session cookie when a session is issued; MFA challenge responses do not set it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaChallengeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Challenge or second factor is invalid, expired, or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stored MFA secret cannot be decrypted", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMfaChallenge", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "mfaChallenge", "allowedPrincipals": [ "mfa-challenge" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "challengeToken" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaChallengeInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Challenge or second factor is invalid, expired, or replayed" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stored MFA secret cannot be decrypted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mfa-challenge-consume", "description": "Atomically consumes the challenge and TOTP step or recovery code." }, { "kind": "session-issue", "description": "Creates a server session and sets its HTTP-only cookie." } ] } } }, "/api/v1/auth/mfa/disable": { "post": { "summary": "Disable MFA after verifying a current second factor", "tags": [ "Auth", "MFA" ], "responses": { "200": { "description": "Disabled MFA and revoked other sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaDisableEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Browser session or second factor is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/platform-admin role or CSRF requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "MFA is not enabled", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stored MFA secret cannot be decrypted", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AuthMfaDisable", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaCodeInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Browser session or second factor is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/platform-admin role or CSRF requirement failed" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "MFA is not enabled" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stored MFA secret cannot be decrypted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revoke-others", "description": "Revokes all other sessions before disabling MFA." }, { "kind": "mfa-disable", "description": "Clears the encrypted MFA secret and recovery-code hashes." } ] } } }, "/api/v1/auth/mfa/recovery": { "post": { "responses": { "200": { "description": "One-time replacement MFA recovery codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaRecoveryRotationEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Browser session or second factor is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/platform-admin role or CSRF requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "MFA is not enabled or changed concurrently", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Authentication rate limit exceeded", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stored MFA secret cannot be decrypted", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaCodeInput" } } } }, "x-vsm-auth-contract": "vsm-auth-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Browser session or second factor is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/platform-admin role or CSRF requirement failed" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "MFA is not enabled or changed concurrently" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Authentication rate limit exceeded" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stored MFA secret cannot be decrypted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mfa-recovery-rotate", "description": "Invalidates every previous recovery code and stores ten new user-bound hashes." }, { "kind": "session-revoke-others", "description": "Revokes all other sessions after code replacement." }, { "kind": "security-audit", "description": "Appends an immutable recovery-code rotation event." } ] }, "operationId": "postApiV1AuthMfaRecovery", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/tenants": { "get": { "summary": "List tenants", "tags": [ "Tenants" ], "responses": { "200": { "description": "Cursor page of joined Tenants or the Platform-Admin tenant inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPageEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Tenants", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create tenant", "tags": [ "Tenants" ], "responses": { "200": { "description": "Platform-Admin provisioned Tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Tenants", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCreateInput" } } } }, "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the Tenant in the configured foundation store" } ] } } }, "/api/v1/tenants/{tenantId}": { "get": { "summary": "Read tenant", "tags": [ "Tenants" ], "responses": { "200": { "description": "Exact authorized Tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TenantsByTenantId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update tenant", "tags": [ "Tenants" ], "responses": { "200": { "description": "Updated Tenant; plan writes require Platform-Admin capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1TenantsByTenantId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUpdateInput" } } } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the Tenant in the configured foundation store" } ] } } }, "/api/v1/tenants/{tenantId}/onboarding": { "get": { "summary": "Read guided tenant onboarding state", "tags": [ "Tenants" ], "responses": { "200": { "description": "Tenant plus guided onboarding state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOnboardingEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TenantsByTenantIdOnboarding", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Persist guided tenant onboarding state", "tags": [ "Tenants" ], "responses": { "200": { "description": "Updated guided onboarding state without entitlement mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOnboardingEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1TenantsByTenantIdOnboarding", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantOnboardingUpdateInput" } } } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists normalized onboarding metadata inside Tenant branding" } ] } } }, "/api/v1/tenants/{tenantId}/members": { "get": { "summary": "List tenant members", "tags": [ "Team" ], "responses": { "200": { "description": "Cursor page of tenant-scoped members and invites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberPageEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TenantsByTenantIdMembers", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Prepare team invitation/member record", "tags": [ "Team" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberCreateInput" } } } }, "responses": { "200": { "description": "Pending member plus invite delivery metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberInviteEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TenantsByTenantIdMembers", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped member lifecycle mutation" }, { "kind": "auth-token", "description": "Creates a hashed, expiring, one-time team invite" }, { "kind": "mail", "description": "Queues the tenant-scoped invitation when the public app URL is configured", "conditional": true } ] } } }, "/api/v1/tenants/{tenantId}/members/{memberId}": { "patch": { "summary": "Update tenant member role/status", "tags": [ "Team" ], "responses": { "200": { "description": "Updated member after owner and session guards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1TenantsByTenantIdMembersByMemberId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMemberUpdateInput" } } } }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revocation", "description": "Revokes every session for the member before a role change", "conditional": true }, { "kind": "persistence", "description": "Persists the tenant-scoped member lifecycle mutation" } ] } }, "delete": { "summary": "Remove tenant member", "tags": [ "Team" ], "responses": { "200": { "description": "Deleted member after invite, session, and owner guards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLocationDeletedEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1TenantsByTenantIdMembersByMemberId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "auth-token", "description": "Revokes unused matching invite tokens", "conditional": true }, { "kind": "session-revocation", "description": "Revokes every active session for the removed member" }, { "kind": "persistence", "description": "Persists the tenant-scoped member lifecycle mutation" } ] } } }, "/api/v1/billing/products": { "get": { "summary": "List SaaS plans and add-on products", "tags": [ "Billing" ], "responses": { "200": { "description": "Sanitized SaaS plan and add-on configuration catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingProductsEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BillingProducts", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" } ] }, "parameters": [] } }, "/api/v1/billing/status": { "get": { "summary": "Read tenant subscription, add-ons, and entitlements", "tags": [ "Billing" ], "responses": { "200": { "description": "Owner/Manager tenant Billing and entitlement snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingStatusEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BillingStatus", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [] } }, "/api/v1/billing/connect/status": { "get": { "summary": "Read tenant Stripe Connect payout readiness", "tags": [ "Billing" ], "responses": { "200": { "description": "Owner/Manager tenant payout-readiness snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnectStatusEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BillingConnectStatus", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [] } }, "/api/v1/billing/connect/account": { "post": { "summary": "Create or refresh a tenant Stripe Connect account", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnectAccountInput" } } } }, "responses": { "200": { "description": "Created or refreshed tenant Stripe Connect account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnectAccountEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BillingConnectAccount", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" }, { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" } ] }, "parameters": [] } }, "/api/v1/billing/connect/onboarding": { "post": { "summary": "Create a Stripe-hosted Connect onboarding link", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnectOnboardingInput" } } } }, "responses": { "200": { "description": "Single-use Stripe-hosted Connect onboarding link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnectOnboardingEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BillingConnectOnboarding", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" }, { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" } ] }, "parameters": [] } }, "/api/v1/billing/checkout": { "post": { "summary": "Create Stripe subscription Checkout Session", "tags": [ "Billing" ], "responses": { "200": { "description": "Stripe subscription Checkout Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BillingCheckout", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutInput" } } } }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" }, { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" } ] }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ] } }, "/api/v1/billing/portal": { "post": { "summary": "Create Stripe Customer Portal Session", "tags": [ "Billing" ], "responses": { "200": { "description": "Stripe Customer Portal Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BillingPortal", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalInput" } } } }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" } ] }, "parameters": [] } }, "/api/v1/billing/stripe-webhook": { "post": { "summary": "Receive idempotent Stripe webhook", "tags": [ "Billing" ], "responses": { "200": { "description": "Idempotent signed Stripe receipt and fulfillment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingStripeWebhookEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BillingStripeWebhook", "security": [ { "stripeSignature": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "providerSignature", "allowedPrincipals": [ "provider-signature" ], "credentialLocation": "signature-header", "csrfRequiredForCookieSession": false, "credentialName": "Stripe-Signature" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeWebhookEventInput" } } } }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" }, { "kind": "ticket-fulfillment", "description": "Conditionally fulfills paid Ticket orders or releases expired Checkout holds", "conditional": true }, { "kind": "finance-reconciliation", "description": "Conditionally reconciles Ticket refunds/disputes or Event-credit provider state", "conditional": true }, { "kind": "mail", "description": "Conditionally queues paid Ticket delivery mail", "conditional": true }, { "kind": "webhook", "description": "Conditionally queues sanitized tenant outbound events", "conditional": true } ] }, "parameters": [] } }, "/api/v1/entitlements": { "get": { "summary": "Read resolved tenant entitlements", "tags": [ "Billing" ], "responses": { "200": { "description": "Resolved tenant entitlement list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEntitlementsEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Entitlements", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [] } }, "/api/v1/add-ons/{addOnKey}/activate": { "post": { "summary": "Activate Stripe-backed add-on", "tags": [ "Billing" ], "responses": { "200": { "description": "Activated or already-active Stripe-backed add-on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAddOnMutationEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AddOnsByAddOnKeyActivate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "addOnKey", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" }, { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" } ] } } }, "/api/v1/add-ons/{addOnKey}/deactivate": { "post": { "summary": "Deactivate Stripe-backed add-on", "tags": [ "Billing" ], "responses": { "200": { "description": "Deactivated or already-inactive Stripe-backed add-on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAddOnMutationEnvelope" } } } }, "400": { "description": "Request body, tenant context, or provider signature is invalid", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or provider signature is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant or Owner/Manager billing role denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, add-on, subscription, or Connect account was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Subscription or add-on lifecycle does not allow the mutation", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, add-on key, country, currency, or return URL is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized persistence or fulfillment failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe, PostgreSQL, or required provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AddOnsByAddOnKeyDeactivate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "addOnKey", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-vsm-billing-contract": "vsm-billing-contract-v2", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body, tenant context, or provider signature is invalid" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or provider signature is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant or Owner/Manager billing role denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, add-on, subscription, or Connect account was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Subscription or add-on lifecycle does not allow the mutation" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, add-on key, country, currency, or return URL is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized persistence or fulfillment failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe, PostgreSQL, or required provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Calls Stripe through the shared fail-closed sanitized adapter" }, { "kind": "persistence", "description": "Persists tenant-scoped Billing or Stripe synchronization state" } ] } } }, "/api/v1/locations": { "get": { "summary": "List locations", "tags": [ "Locations" ], "responses": { "200": { "description": "Cursor page of tenant-scoped Locations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationPageEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Locations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create location", "tags": [ "Locations" ], "responses": { "200": { "description": "Created tenant-scoped Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Locations", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCreateInput" } } } }, "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Location lifecycle mutation" } ] } } }, "/api/v1/locations/{locationId}": { "get": { "summary": "Read location", "tags": [ "Locations" ], "responses": { "200": { "description": "Exact tenant-scoped Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LocationsByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update location", "tags": [ "Locations" ], "responses": { "200": { "description": "Owner/Manager-updated tenant-scoped Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1LocationsByLocationId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUpdateInput" } } } }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Location lifecycle mutation" } ] } }, "delete": { "summary": "Delete unused inactive location", "tags": [ "Locations" ], "responses": { "200": { "description": "Deleted unused draft or archived Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLocationDeletedEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1LocationsByLocationId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Location lifecycle mutation" } ] } } }, "/api/v1/calendars": { "get": { "summary": "List calendars", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Calendars", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Created tenant Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Calendars", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-create", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/calendars/{calendarId}": { "get": { "summary": "Read calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CalendarsByCalendarId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "parameters": [ { "name": "calendarId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated tenant Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CalendarsByCalendarId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarUpdateInput" } } } }, "parameters": [ { "name": "calendarId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 96, "pattern": "^\".+\"$" }, "description": "Quoted Calendar.updatedAt from the edited Calendar snapshot; stale versions fail with 409 CONFLICT." } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } }, "delete": { "summary": "Delete unused inactive calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Deleted unused tenant scheduling relation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1CalendarsByCalendarId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "calendarId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-delete", "description": "Deletes the unused tenant-scoped scheduling resource." } ] } } }, "/api/v1/booking-services": { "get": { "summary": "List location-scoped booking services", "tags": [ "Bookings" ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServicePageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingServices", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a location-scoped booking service", "tags": [ "Bookings" ], "responses": { "200": { "description": "Created Location-bound BookingService", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingServices", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-service-create", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/booking-services/{serviceId}": { "get": { "summary": "Read a tenant-bound booking service", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingServicesByServiceId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update a booking service without moving its location", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated Location-bound BookingService", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1BookingServicesByServiceId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingServiceUpdateInput" } } } }, "parameters": [ { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-service-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/booking-resources": { "get": { "summary": "List room, staff, and equipment resources", "tags": [ "Bookings" ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "room", "staff", "equipment" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourcePageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingResources", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a capacity-bearing scheduling resource", "tags": [ "Bookings" ], "responses": { "200": { "description": "Created scheduling resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingResources", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-resource-create", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/booking-resources/{resourceId}": { "get": { "summary": "Read a tenant-bound booking resource", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingResourcesByResourceId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update a booking resource without moving its location", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated scheduling resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1BookingResourcesByResourceId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceUpdateInput" } } } }, "parameters": [ { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-resource-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/booking-resource-allocations": { "get": { "summary": "List concrete resource allocations created for bookings", "tags": [ "Bookings" ], "parameters": [ { "name": "bookingId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resourceId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceAllocationPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingResourceAllocations", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/booking-resource-allocations/{allocationId}": { "get": { "summary": "Read one tenant-bound booking resource allocation", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResourceAllocationEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingResourceAllocationsByAllocationId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "allocationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/calendar-service-assignments": { "get": { "summary": "List booking services assigned to a calendar", "tags": [ "Bookings" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "isDefault", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarServiceAssignmentPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CalendarServiceAssignments", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Assign a same-location booking service to a calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Assigned BookingService to Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarServiceAssignmentEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CalendarServiceAssignments", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarServiceAssignmentCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-service-assign", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/calendar-service-assignments/{assignmentId}": { "patch": { "summary": "Change whether a calendar service is the default", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated Calendar service assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarServiceAssignmentEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CalendarServiceAssignmentsByAssignmentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarServiceAssignmentUpdateInput" } } } }, "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-service-assignment-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } }, "delete": { "summary": "Detach a service from a calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Deleted unused tenant scheduling relation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1CalendarServiceAssignmentsByAssignmentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-service-unassign", "description": "Deletes the unused tenant-scoped scheduling resource." } ] } } }, "/api/v1/calendar-resource-assignments": { "get": { "summary": "List room, staff, and equipment requirements for a calendar", "tags": [ "Bookings" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResourceAssignmentPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CalendarResourceAssignments", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Assign a same-location capacity resource to a calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Assigned capacity resource to Calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResourceAssignmentEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CalendarResourceAssignments", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResourceAssignmentCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-resource-assign", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/calendar-resource-assignments/{assignmentId}": { "patch": { "summary": "Update the required resource quantity", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated Calendar resource requirement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResourceAssignmentEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CalendarResourceAssignmentsByAssignmentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResourceAssignmentUpdateInput" } } } }, "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-resource-assignment-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } }, "delete": { "summary": "Detach a capacity resource from a calendar", "tags": [ "Bookings" ], "responses": { "200": { "description": "Deleted unused tenant scheduling relation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1CalendarResourceAssignmentsByAssignmentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "calendar-resource-unassign", "description": "Deletes the unused tenant-scoped scheduling resource." } ] } } }, "/api/v1/bookings": { "get": { "summary": "List bookings", "tags": [ "Bookings" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "status", "in": "query", "required": false, "description": "Repeatable or comma-separated booking statuses", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "checkedIn", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Bookings", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create booking with availability, capacity, and mail workflow", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Bookings", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCreateInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-create-workflow", "description": "Persists the Booking and capacity resource allocations atomically." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] } } }, "/api/v1/bookings/operator": { "post": { "summary": "Create a pending phone, Walk-in, or internal operator booking through the shared workflow", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorBookingCreateInput" } } } }, "responses": { "200": { "description": "Booking workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsOperator", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "operator-booking-create-workflow", "description": "Persists the Booking and capacity resource allocations atomically." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] } } }, "/api/v1/bookings/exports/{format}": { "get": { "summary": "Download a filtered audited Booking CSV, PDF guest list, or ICS calendar", "tags": [ "Bookings", "Reports" ], "parameters": [ { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "csv", "pdf", "ics" ] } }, { "name": "calendarId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "checkedIn", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Audited Booking export attachment", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/calendar": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingsExportsByFormat", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-export-audit", "description": "Streams the selected attachment and writes one PII-minimal download AuditEvent." } ] } } }, "/api/v1/bookings/{bookingId}": { "get": { "summary": "Read booking", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingsByBookingId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update booking", "tags": [ "Bookings" ], "responses": { "200": { "description": "Updated tenant Booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1BookingsByBookingId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingUpdateInput" } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-update", "description": "Persists the tenant-scoped scheduling mutation." } ] } } }, "/api/v1/bookings/{bookingId}/reschedule": { "post": { "summary": "Reschedule a booking through the availability workflow", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRescheduleInput" } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-reschedule-workflow", "description": "Persists the Booking and capacity resource allocations atomically." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] }, "operationId": "postApiV1BookingsByBookingIdReschedule", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" } } }, "/api/v1/bookings/{bookingId}/confirm": { "post": { "summary": "Confirm pending booking and queue confirmation mail", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking status workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdConfirm", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-confirm", "description": "Transitions the Booking through the shared status workflow." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] } } }, "/api/v1/bookings/{bookingId}/cancel": { "post": { "summary": "Cancel booking and queue cancellation mail", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking status workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdCancel", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-cancel", "description": "Transitions the Booking through the shared status workflow." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] } } }, "/api/v1/bookings/{bookingId}/no-show": { "post": { "summary": "Mark confirmed booking as no-show", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking status workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdNoShow", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-no-show", "description": "Transitions the Booking through the shared status workflow." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true } ] } } }, "/api/v1/bookings/{bookingId}/complete": { "post": { "summary": "Mark confirmed booking as completed", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking status workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdComplete", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-complete", "description": "Transitions the Booking through the shared status workflow." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true }, { "kind": "booking-loyalty-accrual", "description": "Accrues enabled loyalty points immediately or leaves a repairable pending marker.", "conditional": true } ] } } }, "/api/v1/bookings/{bookingId}/check-in": { "post": { "summary": "Idempotently check in one confirmed Booking", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAttendanceInput" } } } }, "responses": { "200": { "description": "Idempotent Booking attendance result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAttendanceCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdCheckIn", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-check-in", "description": "Updates Booking attendance and appends one PII-minimal attendance event when changed." } ] } } }, "/api/v1/bookings/{bookingId}/undo-check-in": { "post": { "summary": "Idempotently revert one confirmed Booking check-in", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAttendanceInput" } } } }, "responses": { "200": { "description": "Idempotent Booking attendance result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAttendanceCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdUndoCheckIn", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-check-in-revert", "description": "Updates Booking attendance and appends one PII-minimal attendance event when changed." } ] } } }, "/api/v1/bookings/{bookingId}/attendance": { "get": { "summary": "List newest-first Booking attendance history", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingAttendanceHistoryEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingsByBookingIdAttendance", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/bookings/{bookingId}/schedule-reminder": { "post": { "summary": "Queue or replace booking reminder mail", "tags": [ "Mail" ], "responses": { "200": { "description": "Atomically accepted or replayed Booking reminder command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReminderEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "A selected Booking or Ticket audience feature is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingsByBookingIdScheduleReminder", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReminderInput" } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "A selected Booking or Ticket audience feature is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/booking-slots": { "get": { "summary": "List persistent tenant booking slots", "tags": [ "Bookings" ], "parameters": [ { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSlotPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingSlots", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/booking-slots/materialize": { "post": { "summary": "Materialize server-derived Calendar availability as persistent BookingSlots", "tags": [ "Bookings", "Seat Maps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSlotMaterializeInput" } } } }, "responses": { "200": { "description": "Idempotently materialized BookingSlots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSlotMaterializeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingSlotsMaterialize", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio", "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-slot-materialize", "description": "Creates only missing persistent BookingSlots from server-owned availability." } ] } } }, "/api/v1/booking-slots/{slotId}": { "get": { "summary": "Read one persistent tenant booking slot", "tags": [ "Bookings" ], "parameters": [ { "name": "slotId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSlotEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1BookingSlotsBySlotId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/booking-slots/{slotId}/walk-ins": { "post": { "summary": "Atomically create an idempotent operator Walk-in and final seat assignments", "tags": [ "Bookings", "Seat Maps" ], "parameters": [ { "name": "slotId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorWalkInInput" } } } }, "responses": { "200": { "description": "Committed or replayed Walk-in aggregate result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorWalkInEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1BookingSlotsBySlotIdWalkIns", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio", "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "walk-in-commit", "description": "Atomically creates or replays the Booking, final assignments, occupancy delta, and audit event." } ] } } }, "/api/v1/loyalty/programs": { "get": { "summary": "List tenant loyalty programmes", "tags": [ "Loyalty" ], "parameters": [ { "name": "includeEnded", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Tenant Loyalty programmes with rules and aggregate metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyPrograms", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/LoyaltyProgramListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a tenant loyalty programme", "tags": [ "Loyalty" ], "responses": { "201": { "description": "Created draft Loyalty programme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyPrograms", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramCreateInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/programs/{programId}": { "get": { "summary": "Read one tenant loyalty programme", "tags": [ "Loyalty" ], "responses": { "200": { "description": "Tenant-scoped Loyalty programme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyProgramsByProgramId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update a tenant loyalty programme with optimistic concurrency", "tags": [ "Loyalty" ], "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 96, "pattern": "^\".+\"$" } } ], "responses": { "200": { "description": "Optimistically updated Loyalty programme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1LoyaltyProgramsByProgramId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramUpdateInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/programs/{programId}/progression": { "get": { "summary": "Read Loyalty levels, badges, challenges, and referrals", "tags": [ "Loyalty" ], "responses": { "200": { "description": "Versioned Loyalty levels, badges, challenges, and referral campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgressionEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LoyaltyProgramsByProgramIdProgression", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" } }, "put": { "summary": "Replace Loyalty levels, badges, challenges, and referrals", "tags": [ "Loyalty" ], "responses": { "200": { "description": "Replaced the complete Loyalty progression configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgressionEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgressionConfigInput" } } } }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 96, "pattern": "^\".+\"$" } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] }, "operationId": "putApiV1LoyaltyProgramsByProgramIdProgression", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/loyalty/programs/{programId}/activate": { "post": { "summary": "Activate a draft or paused loyalty programme", "tags": [ "Loyalty" ], "responses": { "200": { "description": "activate Loyalty programme transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyProgramsByProgramIdActivate", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/programs/{programId}/pause": { "post": { "summary": "Pause an active loyalty programme", "tags": [ "Loyalty" ], "responses": { "200": { "description": "pause Loyalty programme transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyProgramsByProgramIdPause", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/programs/{programId}/end": { "post": { "summary": "Permanently end a loyalty programme", "tags": [ "Loyalty" ], "responses": { "200": { "description": "end Loyalty programme transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyProgramEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyProgramsByProgramIdEnd", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/programs/{programId}/adjustments": { "post": { "summary": "Append an idempotent manual wallet adjustment", "tags": [ "Loyalty" ], "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Idempotent manual Wallet adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyAppendEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyProgramsByProgramIdAdjustments", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyAdjustmentInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Appends immutable Loyalty ledger data and updates the locked Wallet projection transactionally" } ] } } }, "/api/v1/loyalty/programs/{programId}/stamp-tokens": { "post": { "summary": "Create a short-lived single-use loyalty stamp token", "tags": [ "Loyalty" ], "responses": { "201": { "description": "One-time short-lived Loyalty stamp token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyStampTokenEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyProgramsByProgramIdStampTokens", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyStampTokenInput" } } } }, "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only a one-time token hash and returns the raw token only in the first response" } ] } } }, "/api/v1/loyalty/ledger": { "get": { "summary": "Read the immutable tenant loyalty ledger", "tags": [ "Loyalty" ], "parameters": [ { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Bounded immutable Loyalty ledger projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyLedgerListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyLedger", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/LoyaltyLedgerQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/loyalty/rewards": { "get": { "summary": "List tenant loyalty rewards", "tags": [ "Loyalty" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "issued", "redeemed", "voided" ] } } ], "responses": { "200": { "description": "Tenant Loyalty rewards filtered by lifecycle status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyRewardListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyRewards", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/LoyaltyRewardQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/loyalty/rewards/redeem": { "post": { "summary": "Redeem a single-use loyalty reward token", "tags": [ "Loyalty" ], "responses": { "200": { "description": "Redeemed one-time Customer reward token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyRewardEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyRewardsRedeem", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyRewardRedeemInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/rewards/{rewardId}/void": { "post": { "summary": "Void an issued reward and append one wallet reversal", "tags": [ "Loyalty" ], "parameters": [ { "name": "rewardId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Voided reward with one exact Wallet reversal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyRewardVoidEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyRewardsByRewardIdVoid", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyRewardVoidInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Appends immutable Loyalty ledger data and updates the locked Wallet projection transactionally" } ] } } }, "/api/v1/loyalty/coupons": { "get": { "summary": "List tenant coupons with quota metrics", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "includeEnded", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Tenant Coupons with live quota metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyCoupons", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CouponListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a tenant and location-scoped coupon", "tags": [ "Loyalty", "Coupons" ], "responses": { "201": { "description": "Created draft location Coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCoupons", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreateInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/coupons/{couponId}": { "get": { "summary": "Read one tenant coupon", "tags": [ "Loyalty", "Coupons" ], "responses": { "200": { "description": "Tenant-scoped Coupon with quota metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyCouponsByCouponId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update a paused or draft coupon with optimistic concurrency", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 96, "pattern": "^\".+\"$" } } ], "responses": { "200": { "description": "Optimistically updated draft or paused Coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1LoyaltyCouponsByCouponId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpdateInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/coupons/{couponId}/activate": { "post": { "summary": "Activate a draft or paused coupon", "tags": [ "Loyalty", "Coupons" ], "responses": { "200": { "description": "activate Coupon lifecycle transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponsByCouponIdActivate", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/coupons/{couponId}/pause": { "post": { "summary": "Pause an active coupon", "tags": [ "Loyalty", "Coupons" ], "responses": { "200": { "description": "pause Coupon lifecycle transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponsByCouponIdPause", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/coupons/{couponId}/end": { "post": { "summary": "Permanently end a coupon", "tags": [ "Loyalty", "Coupons" ], "responses": { "200": { "description": "end Coupon lifecycle transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponsByCouponIdEnd", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/v1/loyalty/coupons/{couponId}/redeem": { "post": { "summary": "Redeem coupon quantity through an operator", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "201": { "description": "Idempotent manual Coupon redemption", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponsByCouponIdRedeem", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Consumes or reverses Coupon quota and persists the immutable redemption transition transactionally" }, { "kind": "worker", "description": "May enqueue or leave a repairable Coupon-triggered Loyalty accrual", "conditional": true } ] } } }, "/api/v1/loyalty/coupons/{couponId}/offline-vouchers": { "post": { "summary": "Preissue signed same-day offline vouchers", "tags": [ "Loyalty", "Coupons", "Offline" ], "parameters": [ { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "201": { "description": "Signed, device-scoped offline Voucher package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponOfflineIssueEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponsByCouponIdOfflineVouchers", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponOfflineIssueInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reserves Coupon quota and stores only signed Voucher hashes, hints, device scope, and expiry" } ] } } }, "/api/v1/loyalty/coupon-redemptions": { "get": { "summary": "List tenant coupon redemptions", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "couponId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "redeemed", "voided" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Bounded Coupon redemption history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyCouponRedemptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CouponRedemptionQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/loyalty/coupon-redemptions/scan": { "post": { "summary": "Redeem one short-lived customer claim token", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "201": { "description": "Idempotent Customer Claim scan redemption", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponRedemptionsScan", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponScanInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Consumes or reverses Coupon quota and persists the immutable redemption transition transactionally" }, { "kind": "worker", "description": "May enqueue or leave a repairable Coupon-triggered Loyalty accrual", "conditional": true } ] } } }, "/api/v1/loyalty/coupon-redemptions/{redemptionId}/void": { "post": { "summary": "Void a redemption and atomically reverse awarded Loyalty", "tags": [ "Loyalty", "Coupons" ], "parameters": [ { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Voided Coupon redemption with quota and Loyalty reversal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponRedemptionsByRedemptionIdVoid", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponRedemptionVoidInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Consumes or reverses Coupon quota and persists the immutable redemption transition transactionally" }, { "kind": "worker", "description": "May enqueue or leave a repairable Coupon-triggered Loyalty accrual", "conditional": true } ] } } }, "/api/v1/loyalty/coupon-offline/sync": { "post": { "summary": "Verify and reconcile signed offline coupon events", "tags": [ "Loyalty", "Coupons", "Offline" ], "responses": { "200": { "description": "Per-event offline Voucher synchronization result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponOfflineSyncEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1LoyaltyCouponOfflineSync", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponOfflineSyncInput" } } } }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Consumes or reverses Coupon quota and persists the immutable redemption transition transactionally" }, { "kind": "worker", "description": "May enqueue or leave a repairable Coupon-triggered Loyalty accrual", "conditional": true } ] } } }, "/api/v1/loyalty/coupon-voucher-batches": { "get": { "summary": "List offline voucher batch metadata without raw codes", "tags": [ "Loyalty", "Coupons", "Offline" ], "responses": { "200": { "description": "Offline Voucher batch history without raw codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponVoucherBatchListEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LoyaltyCouponVoucherBatches", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" }, "parameters": [ { "name": "couponId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CouponVoucherBatchQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/coupons": { "get": { "summary": "Read the verified customer's private coupon center", "tags": [ "Customer Account", "Loyalty", "Coupons" ], "responses": { "200": { "description": "Private Customer Coupon catalog, Claims, and redemptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCouponCenterEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugCoupons", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/coupons/{couponId}/claim": { "post": { "summary": "Claim a short-lived single-use coupon token", "tags": [ "Customer Account", "Loyalty", "Coupons" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "couponId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "201": { "description": "Idempotent Customer Coupon Claim with one-time scan token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCouponClaimEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugCouponsByCouponIdClaim", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only a one-time token hash and returns the raw token only in the first response" } ] } } }, "/api/v1/customer-account/{tenantSlug}/coupon-claims/{claimId}/refresh": { "post": { "summary": "Rotate an owned pending coupon claim token", "tags": [ "Customer Account", "Loyalty", "Coupons" ], "responses": { "200": { "description": "Rotated owned Claim scan token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCouponClaimEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugCouponClaimsByClaimIdRefresh", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only a one-time token hash and returns the raw token only in the first response" } ] } } }, "/api/v1/customer-account/{tenantSlug}/coupon-claims/{claimId}/cancel": { "post": { "summary": "Cancel an owned pending coupon claim", "tags": [ "Customer Account", "Loyalty", "Coupons" ], "responses": { "200": { "description": "Cancelled owned pending Coupon Claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCouponCancelEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugCouponClaimsByClaimIdCancel", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "claimId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/coupons": { "get": { "summary": "List active public coupons for one active Location", "tags": [ "Public", "Loyalty", "Coupons" ], "responses": { "200": { "description": "Currently active public Coupons for one active Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCouponCatalogEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicByTenantSlugByLocationSlugCoupons", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/loyalty": { "get": { "summary": "Read the verified customer's loyalty wallet", "tags": [ "Customer Account", "Loyalty" ], "responses": { "200": { "description": "Private Customer Loyalty Wallet and owned rewards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyWalletEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugLoyalty", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/loyalty/stamp": { "post": { "summary": "Redeem a single-use stamp token into the verified customer wallet", "tags": [ "Customer Account", "Loyalty" ], "responses": { "200": { "description": "Redeemed one-time Loyalty stamp token into the owned Wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyAppendEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugLoyaltyStamp", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyStampInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Appends immutable Loyalty ledger data and updates the locked Wallet projection transactionally" } ] } } }, "/api/v1/customer-account/{tenantSlug}/loyalty/{programId}/reward": { "post": { "summary": "Issue one idempotent reward from the verified customer wallet", "tags": [ "Customer Account", "Loyalty" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Issued one Customer reward and debited exact required stamps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyRewardIssueEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugLoyaltyByProgramIdReward", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Appends immutable Loyalty ledger data and updates the locked Wallet projection transactionally" } ] } } }, "/api/v1/customer-account/{tenantSlug}/loyalty/{programId}/referral": { "post": { "summary": "Create a private Customer referral link", "tags": [ "Customer Account", "Loyalty" ], "responses": { "201": { "description": "Issued a private one-time Customer referral link for an active campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyReferralIssueEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only a one-time token hash and returns the raw token only in the first response" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugLoyaltyByProgramIdReferral", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/customer-account/{tenantSlug}/loyalty/referrals/{token}": { "post": { "summary": "Claim a private Customer referral", "tags": [ "Customer Account", "Loyalty" ], "responses": { "200": { "description": "Claimed a private referral for the verified Customer account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoyaltyReferralClaimEnvelope" } } } }, "401": { "description": "An authenticated tenant or verified Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the loyalty.programs entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The actor lacks the required tenant role or Customer ownership", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, header, or strict JSON input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public or Customer request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing persistence, token, or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-loyalty-contract": "vsm-loyalty-coupon-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant or verified Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the loyalty.programs entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The actor lacks the required tenant role or Customer ownership" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Loyalty, Coupon, Customer, or Location resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The lifecycle, quota, token, Wallet, optimistic-lock, or idempotency transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, header, or strict JSON input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public or Customer request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing persistence, token, or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or the offline Voucher signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped lifecycle mutation and immutable audit evidence" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugLoyaltyReferralsByToken", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/customer-account/{tenantSlug}/event-credits": { "get": { "summary": "List the verified customer's Event Credit wallets", "tags": [ "Customer Account", "Events", "Payments" ], "responses": { "200": { "description": "All Event Credit wallets owned by the Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditWalletListEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant has no active Event Credits entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugEventCredits", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant has no active Event Credits entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/event-credits/{eventId}": { "get": { "summary": "Read one verified customer Event Credit wallet", "tags": [ "Customer Account", "Events", "Payments" ], "responses": { "200": { "description": "One Event-scoped Customer Credit wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditWalletEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant has no active Event Credits entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugEventCreditsByEventId", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant has no active Event Credits entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/event-credits/{eventId}/topup": { "post": { "summary": "Prepare an idempotent Stripe Event Credit top-up", "tags": [ "Customer Account", "Events", "Payments" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditTopUpInput" } } } }, "responses": { "202": { "description": "Pending Stripe Event Credit top-up prepared for signed webhook settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditPaymentPreparationEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant has no active Event Credits entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugEventCreditsByEventIdTopup", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant has no active Event Credits entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates or replays one request-hashed pending top-up transaction" }, { "kind": "provider", "description": "Creates or retrieves one Stripe PaymentIntent with stable idempotency" }, { "kind": "webhook", "description": "Credits the immutable wallet ledger only after a verified provider callback", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}/event-credits/{eventId}/charge-token": { "post": { "summary": "Issue a short-lived single-use Event Credit charge token", "tags": [ "Customer Account", "Events", "Payments" ], "responses": { "201": { "description": "One-time Event Credit QR bearer and manual fallback code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditChargeTokenEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant has no active Event Credits entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugEventCreditsByEventIdChargeToken", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditChargeTokenInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant has no active Event Credits entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Stores only HMAC hashes, the authorization scope and non-secret hint" }, { "kind": "security", "description": "Returns the random token, manual code and QR payload exactly once" } ] } } }, "/api/v1/customer-account/{tenantSlug}/event-credits/{eventId}/refund": { "post": { "summary": "Refund post-event residual credit to original Stripe payments", "tags": [ "Customer Account", "Events", "Payments" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "202": { "description": "Idempotent original-payment Event Credit cash-refund result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditTransactionEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant has no active Event Credits entitlement", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugEventCreditsByEventIdRefund", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventCreditRefundInput" } } } }, "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant has no active Event Credits entitlement" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reserves and finalizes the refund transaction plus one immutable negative ledger entry" }, { "kind": "provider", "description": "Refunds only allocated succeeded original Stripe top-ups with stable idempotency" } ] } } }, "/api/v1/customer-profiles/search": { "post": { "summary": "Resolve customer profile by normalized email hash", "tags": [ "Communication" ], "responses": { "200": { "description": "Aggregated tenant Customer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "A selected Booking or Ticket audience feature is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerProfilesSearch", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileSearchInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking", "ticketing.checkout" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "A selected Booking or Ticket audience feature is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-profiles/{customerKey}": { "get": { "summary": "Read customer profile by customer hash key", "tags": [ "Communication" ], "responses": { "200": { "description": "Aggregated tenant Customer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "A selected Booking or Ticket audience feature is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerProfilesByCustomerKey", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "customerKey", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking", "ticketing.checkout" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "A selected Booking or Ticket audience feature is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/access": { "post": { "summary": "Request a tenant-specific passwordless customer-account link", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Enumeration-safe Customer access acceptance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountAccessEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugAccess", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountAccessInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Ensures the matching passwordless User shell", "conditional": true }, { "kind": "mail", "description": "Queues one tenant-bound single-use Customer Magic Link", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}": { "get": { "summary": "Read the verified customer's tenant account, bookings and ticket wallet", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Exact verified Customer account overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlug", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/deletion": { "get": { "summary": "Read a private customer-account erasure status by personal session or recovery token", "tags": [ "Customer Account", "Privacy" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "X-VSM-Deletion-Token", "in": "header", "required": false, "schema": { "type": "string", "minLength": 32, "maxLength": 256 } } ], "responses": { "200": { "description": "Private Customer erasure status by session or recovery token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugDeletion", "security": [ { "customerSession": [] }, {} ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSessionOrSignedToken", "allowedPrincipals": [ "customer-session", "signed-token" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_privacy_erasure_recovery" }, "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Request verified customer-account erasure with a 30-day recovery period", "tags": [ "Customer Account", "Privacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionRequestInput" } } } }, "responses": { "202": { "description": "Scheduled Customer erasure with one-time recovery handoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugDeletion", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates the privacy request, Customer timeline event, and SupportCase" }, { "kind": "session", "description": "Revokes every User session and clears the current session cookie" }, { "kind": "worker", "description": "Schedules bounded provider-aware erasure after the grace period" } ] } } }, "/api/v1/customer-account/{tenantSlug}/deletion/exchange": { "post": { "summary": "Exchange a short-lived erasure recovery code", "tags": [ "Customer Account", "Privacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionExchangeInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Exchanged a short-lived one-time recovery code for an HttpOnly recovery session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session", "description": "Consumes the URL code once and sets a tenant-scoped HttpOnly recovery cookie" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugDeletionExchange", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "code" } } }, "/api/v1/customer-account/{tenantSlug}/deletion/cancel": { "post": { "summary": "Cancel a pending tenant-bound customer-account erasure by recovery token", "tags": [ "Customer Account", "Privacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionCancelInput" } } } }, "responses": { "200": { "description": "Cancelled pending Customer erasure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountDeletionEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugDeletionCancel", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_privacy_erasure_recovery" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Cancels only the tenant-bound pending or failed erasure request" } ] } } }, "/api/v1/customer-account/{tenantSlug}/preferences": { "patch": { "summary": "Update tenant-specific operational customer preferences", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Updated Customer account preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPreferencesEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CustomerAccountByTenantSlugPreferences", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPreferencesInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Upserts the tenant and Customer-bound preference row" } ] } } }, "/api/v1/customer-account/{tenantSlug}/notification-preferences": { "get": { "summary": "Read resolved topic/channel preferences and safe registered-device views", "tags": [ "Customer Account", "Communication" ], "responses": { "200": { "description": "Resolved versioned notification preferences and sanitized Push devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountNotificationSettingsEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugNotificationPreferences", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update revisioned topic/channel notification preferences", "tags": [ "Customer Account", "Communication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountNotificationPreferenceUpdateInput" } } } }, "responses": { "200": { "description": "Updated revisioned Customer notification preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountNotificationPreferencesEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CustomerAccountByTenantSlugNotificationPreferences", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Upserts sparse revisioned preferences and synchronizes the legacy projection" } ] } } }, "/api/v1/customer-account/{tenantSlug}/push-devices": { "get": { "summary": "Read the resolved notification settings and safe registered-device views", "tags": [ "Customer Account", "Communication" ], "responses": { "200": { "description": "Resolved notification settings and sanitized Customer Push devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountNotificationSettingsEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugPushDevices", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Register a Customer push device through the configured provider gateway", "tags": [ "Customer Account", "Communication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDeviceRegistrationInput" } } } }, "responses": { "200": { "description": "Registered or idempotently refreshed Push device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDeviceEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugPushDevices", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "provider", "description": "Registers the raw token with the configured HTTPS Push gateway" }, { "kind": "persistence", "description": "Stores only HMAC identifiers, provider handle and sanitized device metadata" } ] } } }, "/api/v1/customer-account/{tenantSlug}/push-devices/{deviceId}/rotate": { "patch": { "summary": "Rotate one owned Customer push-device registration", "tags": [ "Customer Account", "Communication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDeviceRegistrationInput" } } } }, "responses": { "200": { "description": "Rotated an owned Customer Push device token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDeviceEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CustomerAccountByTenantSlugPushDevicesByDeviceIdRotate", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "provider", "description": "Registers the replacement token against the previous provider handle" }, { "kind": "persistence", "description": "Replaces HMAC token state and records the rotation timestamp" } ] } } }, "/api/v1/customer-account/{tenantSlug}/push-devices/{deviceId}": { "delete": { "summary": "Revoke one owned Customer push device locally and at the provider", "tags": [ "Customer Account", "Communication" ], "responses": { "200": { "description": "Locally revoked Push device with best-effort provider cleanup result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDeviceRevokeEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1CustomerAccountByTenantSlugPushDevicesByDeviceId", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Idempotently marks the owned local Push device revoked first" }, { "kind": "provider", "description": "Attempts best-effort provider cleanup without rolling back local revocation", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}/push-diagnostics": { "post": { "summary": "Report one privacy-minimized Customer push diagnostic", "tags": [ "Customer Account", "Communication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDiagnosticInput" } } } }, "responses": { "200": { "description": "Accepted one privacy-minimized client Push diagnostic report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPushDiagnosticEnvelope" } } } }, "400": { "description": "The JSON request is malformed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The bounded JSON request exceeds the accepted size", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "The JSON request is malformed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The bounded JSON request exceeds the accepted size" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "Writes one structured warning log with a pseudonymized tenant hash only" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugPushDiagnostics", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/conversations": { "get": { "summary": "List operator-visible Customer conversations", "tags": [ "Communication", "Conversations" ], "responses": { "200": { "description": "Visible Customer conversation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorConversationListEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Conversations", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/OperatorConversationListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a Customer conversation as an operator", "tags": [ "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorConversationCreateInput" } } } }, "responses": { "200": { "description": "Conversation created idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Conversations", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/conversations/{threadId}": { "get": { "summary": "Read one operator-visible conversation", "tags": [ "Communication", "Conversations" ], "responses": { "200": { "description": "Owned conversation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1ConversationsByThreadId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/conversations/{threadId}/messages": { "post": { "summary": "Append a public reply or internal operator note", "tags": [ "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReplyInput" } } } }, "responses": { "200": { "description": "Conversation reply appended idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1ConversationsByThreadIdMessages", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/conversations/{threadId}/read": { "post": { "summary": "Advance the operator participant read marker", "tags": [ "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReadInput" } } } }, "responses": { "200": { "description": "Participant read marker advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1ConversationsByThreadIdRead", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/conversations/{threadId}/close": { "post": { "summary": "Close an open conversation with revision compare-and-set", "tags": [ "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCloseInput" } } } }, "responses": { "200": { "description": "Conversation closed with revision compare-and-set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1ConversationsByThreadIdClose", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/conversations/{threadId}/assignment": { "post": { "summary": "Close an open conversation with revision compare-and-set", "tags": [ "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationAssignmentInput" } } } }, "responses": { "200": { "description": "Responsible operator set or cleared with revision compare-and-set and audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1ConversationsByThreadIdAssignment", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/conversations/{threadId}/attachments/{attachmentId}": { "get": { "summary": "Download an operator-visible immutable text attachment", "tags": [ "Communication", "Conversations" ], "responses": { "200": { "description": "Private immutable text attachment", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CommunicationTextAttachment" } } }, "headers": { "Cache-Control": { "description": "Private no-store attachment response", "schema": { "type": "string", "const": "private, no-store, max-age=0" } }, "Content-Disposition": { "description": "Sanitized ASCII and RFC 5987 UTF-8 file names", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Disables MIME sniffing", "schema": { "type": "string", "const": "nosniff" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1ConversationsByThreadIdAttachmentsByAttachmentId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/conversations": { "get": { "summary": "List the verified Customer's conversations", "tags": [ "Customer Account", "Communication", "Conversations" ], "responses": { "200": { "description": "Visible Customer conversation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationListEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugConversations", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed" ] } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CustomerConversationListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a conversation as the verified Customer", "tags": [ "Customer Account", "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCreateInput" } } } }, "responses": { "200": { "description": "Conversation created idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerConversationCreateEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugConversations", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/customer-account/{tenantSlug}/conversations/{threadId}": { "get": { "summary": "Read one Customer-owned conversation without internal notes", "tags": [ "Customer Account", "Communication", "Conversations" ], "responses": { "200": { "description": "Owned conversation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugConversationsByThreadId", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/conversations/{threadId}/messages": { "post": { "summary": "Append a public Customer reply", "tags": [ "Customer Account", "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerConversationReplyInput" } } } }, "responses": { "200": { "description": "Conversation reply appended idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugConversationsByThreadIdMessages", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/customer-account/{tenantSlug}/conversations/{threadId}/read": { "post": { "summary": "Advance the Customer participant read marker", "tags": [ "Customer Account", "Communication", "Conversations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReadInput" } } } }, "responses": { "200": { "description": "Participant read marker advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThreadEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugConversationsByThreadIdRead", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/customer-account/{tenantSlug}/conversations/{threadId}/attachments/{attachmentId}": { "get": { "summary": "Download a Customer-visible immutable text attachment", "tags": [ "Customer Account", "Communication", "Conversations" ], "responses": { "200": { "description": "Private immutable text attachment", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CommunicationTextAttachment" } } }, "headers": { "Cache-Control": { "description": "Private no-store attachment response", "schema": { "type": "string", "const": "private, no-store, max-age=0" } }, "Content-Disposition": { "description": "Sanitized ASCII and RFC 5987 UTF-8 file names", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Disables MIME sniffing", "schema": { "type": "string", "const": "nosniff" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugConversationsByThreadIdAttachmentsByAttachmentId", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/alerts/{alertId}/open": { "post": { "summary": "Mark an owned delivered in-app Event alert as opened", "tags": [ "Customer Account", "Events" ], "responses": { "200": { "description": "Idempotently marked an owned delivered alert opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventAlertInteractionEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugAlertsByAlertIdOpen", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Sets the first open timestamp only on the owned delivered in-app alert" } ] } } }, "/api/v1/customer-account/{tenantSlug}/alerts/{alertId}/click": { "post": { "summary": "Mark an owned delivered in-app Event alert as clicked", "tags": [ "Customer Account", "Events" ], "responses": { "200": { "description": "Idempotently marked an owned delivered alert opened and clicked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountEventAlertInteractionEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugAlertsByAlertIdClick", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Sets first open/click timestamps only on the owned delivered in-app alert" } ] } } }, "/api/v1/customer-account/{tenantSlug}/bookings/{bookingId}/cancel": { "post": { "summary": "Cancel one Booking owned by the verified customer account", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Cancelled owned Booking with workflow evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountBookingCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugBookingsByBookingIdCancel", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountBookingCancelInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Applies the shared Booking cancellation workflow and writes a Customer-linked SupportCase" }, { "kind": "mail", "description": "Queues the applicable Booking customer mail", "conditional": true }, { "kind": "webhook", "description": "Queues the corresponding signed Booking webhook", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}/bookings/{bookingId}/reschedule": { "post": { "summary": "Reschedule one Booking owned by the verified customer account", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Rescheduled owned Booking with workflow evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountBookingCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugBookingsByBookingIdReschedule", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountBookingRescheduleInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Applies the shared Booking reschedule workflow and writes a Customer-linked SupportCase" }, { "kind": "mail", "description": "Queues the applicable Booking customer mail", "conditional": true }, { "kind": "webhook", "description": "Queues the corresponding signed Booking webhook", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}/tickets/{ticketId}/pdf": { "get": { "summary": "Download an owned Ticket PDF generated from current server state", "tags": [ "Customer Account" ], "responses": { "200": { "description": "Current on-demand owned Ticket PDF", "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketPdf" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugTicketsByTicketIdPdf", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/ticket-transfers": { "get": { "summary": "List incoming and outgoing ticket transfers for the verified customer", "tags": [ "Customer Account", "Ticketing" ], "responses": { "200": { "description": "Incoming and outgoing Customer Ticket transfers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransfersEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomerAccountByTenantSlugTicketTransfers", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customer-account/{tenantSlug}/tickets/{ticketId}/transfer": { "post": { "summary": "Invite a recipient to take ownership of one current ticket", "tags": [ "Customer Account", "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCreateInput" } } } }, "responses": { "200": { "description": "Idempotently created secure Ticket transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugTicketsByTicketIdTransfer", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Stores a hash-only transfer, recipient Customer shell, and immutable audit evidence" }, { "kind": "mail", "description": "Queues the one-time transfer invitation without exposing the raw token in JSON" } ] } }, "delete": { "summary": "Revoke the current holder's pending ticket-transfer invitation", "tags": [ "Customer Account", "Ticketing" ], "responses": { "200": { "description": "Revoked pending owned Ticket transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1CustomerAccountByTenantSlugTicketsByTicketIdTransfer", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Applies the serializable Ticket-transfer revocation and immutable lifecycle audit" }, { "kind": "mail", "description": "Queues the applicable transfer lifecycle notifications", "conditional": true } ] } } }, "/api/v1/customer-account/{tenantSlug}/ticket-transfers/{token}/accept": { "post": { "summary": "Accept a token-bound ticket transfer and rotate current access", "tags": [ "Customer Account", "Ticketing" ], "responses": { "200": { "description": "Accepted invited Ticket transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugTicketTransfersByTokenAccept", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Applies the serializable Ticket-transfer acceptance and immutable lifecycle audit" }, { "kind": "mail", "description": "Queues the applicable transfer lifecycle notifications", "conditional": true }, { "kind": "security", "description": "Rotates the Ticket access code/QR and revokes active offline scanner packages" } ] } } }, "/api/v1/customer-account/{tenantSlug}/ticket-transfers/{token}/decline": { "post": { "summary": "Decline a token-bound pending ticket transfer", "tags": [ "Customer Account", "Ticketing" ], "responses": { "200": { "description": "Declined invited Ticket transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCommandEnvelope" } } } }, "401": { "description": "A personal Customer session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "The verified Customer does not own this tenant resource", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The path, query, body, or idempotency key is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomerAccountByTenantSlugTicketTransfersByTokenDecline", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "A personal Customer session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "The verified Customer does not own this tenant resource" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "The requested account, Booking, privacy, or transfer transition conflicts with current state" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The path, query, body, or idempotency key is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Applies the serializable Ticket-transfer decline and immutable lifecycle audit" }, { "kind": "mail", "description": "Queues the applicable transfer lifecycle notifications", "conditional": true } ] } } }, "/api/v1/customers": { "get": { "summary": "List and search durable tenant customer profiles", "tags": [ "Customers" ], "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "segment", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "consent", "in": "query", "schema": { "type": "string", "enum": [ "unknown", "granted", "denied" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Cursor page of tenant-scoped Customer summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerListEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or customers API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Filter, cursor, profile update, or merge target is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Customers", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/OperatorCustomerListQuery" }, "x-vsm-customer-management-contract": "vsm-customer-management-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or customers API scope denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Filter, cursor, profile update, or merge target is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/customers/{customerId}": { "get": { "summary": "Read one durable customer profile and cross-domain timeline", "tags": [ "Customers" ], "responses": { "200": { "description": "Customer profile, contacts, duplicates, and timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerProfileEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or customers API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Active tenant-scoped Customer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Filter, cursor, profile update, or merge target is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CustomersByCustomerId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-management-contract": "vsm-customer-management-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or customers API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Active tenant-scoped Customer was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Filter, cursor, profile update, or merge target is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update customer identity metadata, segments, locale, and consent state", "tags": [ "Customers" ], "responses": { "200": { "description": "Updated Customer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerProfileEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or customers API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Active tenant-scoped Customer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Concurrent merge or linked-account identity conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Filter, cursor, profile update, or merge target is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1CustomersByCustomerId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerUpdateInput" } } } }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-management-contract": "vsm-customer-management-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or customers API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Active tenant-scoped Customer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Concurrent merge or linked-account identity conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Filter, cursor, profile update, or merge target is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Customer profile and identity-link state" }, { "kind": "audit", "description": "Writes immutable Customer profile lifecycle events" } ] } } }, "/api/v1/customers/{customerId}/merge": { "post": { "summary": "Merge one duplicate customer into a canonical target atomically", "tags": [ "Customers" ], "responses": { "200": { "description": "Canonical Customer profile after atomic merge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerProfileEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or customers API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Active tenant-scoped Customer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Concurrent merge or linked-account identity conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Filter, cursor, profile update, or merge target is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1CustomersByCustomerIdMerge", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCustomerMergeInput" } } } }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-customer-management-contract": "vsm-customer-management-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or customers API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Active tenant-scoped Customer was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Concurrent merge or linked-account identity conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Filter, cursor, profile update, or merge target is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Customer profile and identity-link state" }, { "kind": "audit", "description": "Writes immutable Customer profile lifecycle events" }, { "kind": "cross-domain-rewrite", "description": "Atomically moves owned Booking, Ticket, Mail, Support, preference and device links to the canonical Customer" } ] } } }, "/api/v1/waitlist": { "get": { "summary": "List ranked slot-bound tenant waitlist entries", "tags": [ "Communication" ], "responses": { "200": { "description": "Ranked slot-bound Waitlist entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistListEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Waitlist", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "slotId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "waiting", "offered", "promoted", "cancelled", "expired", "removed" ] } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WaitlistListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/waitlist/group-calls/preview": { "get": { "summary": "List ranked slot-bound tenant waitlist entries", "tags": [ "Communication" ], "responses": { "200": { "description": "F20 recipients that fully fit the free places, excluded large groups and the coexistence block reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistGroupCallPreviewEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WaitlistGroupCallsPreview", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "slotId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/waitlist/group-calls": { "post": { "summary": "Promote one waitlist entry to a confirmed booking", "tags": [ "Communication" ], "responses": { "200": { "description": "F20 non-exclusive group call queued once per UUID; refused next to an active exclusive offer or call", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistGroupCallEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WaitlistGroupCalls", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistGroupCallInput" } } } } } }, "/api/v1/waitlist/{caseId}/notify": { "post": { "summary": "Compatibility alias to offer one waitlist entry", "tags": [ "Communication" ], "responses": { "200": { "description": "Capacity offered with 90-day UUID replay; unkeyed offered-entry reads never resend, while renewal requires a fresh UUID and known terminal predecessor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistOfferEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WaitlistByCaseIdNotify", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistOfferInput" } } } }, "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/waitlist/{entryId}/offer": { "post": { "summary": "Offer capacity to one ranked waitlist entry idempotently", "tags": [ "Communication" ], "responses": { "200": { "description": "Capacity offered with 90-day UUID replay; unkeyed offered-entry reads never resend, while renewal requires a fresh UUID and known terminal predecessor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistOfferEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WaitlistByEntryIdOffer", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistOfferInput" } } } }, "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/waitlist/{entryId}/promote": { "post": { "summary": "Promote one waitlist entry to a confirmed booking", "tags": [ "Communication" ], "responses": { "200": { "description": "Waitlist entry promoted to confirmed Booking idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistPromotionEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WaitlistByEntryIdPromote", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/support-cases": { "get": { "summary": "List tenant support cases with SLA state", "tags": [ "Communication", "Support" ], "responses": { "200": { "description": "Tenant Support case queue with current SLA state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleListEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/SupportCaseListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1SupportCases", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/support-cases/{caseId}": { "get": { "summary": "Read support case lifecycle detail", "tags": [ "Communication", "Support" ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Support case, conversation, and append-only audit history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1SupportCasesByCaseId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/support-cases/{caseId}/status": { "post": { "summary": "Change support case status", "tags": [ "Communication", "Support" ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Support case status changed with revision guard and audit event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseStatusInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] }, "operationId": "postApiV1SupportCasesByCaseIdStatus", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/support-cases/{caseId}/assign": { "post": { "summary": "Assign support case", "tags": [ "Communication" ], "responses": { "200": { "description": "Support case assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SupportCasesByCaseIdAssign", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseAssignInput" } } } }, "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/support-cases/{caseId}/comment": { "post": { "summary": "Add internal support-case comment", "tags": [ "Communication" ], "responses": { "200": { "description": "Internal Support case comment stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SupportCasesByCaseIdComment", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseCommentInput" } } } }, "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client request id for idempotent creation/reply" } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/support-cases/{caseId}/resolve": { "post": { "summary": "Resolve support case", "tags": [ "Communication" ], "responses": { "200": { "description": "Support case resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SupportCasesByCaseIdResolve", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/email-templates": { "get": { "summary": "List tenant email templates", "tags": [ "Mail" ], "responses": { "200": { "description": "Cursor-paginated tenant Email templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplatePageEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EmailTemplates", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CommunicationMailListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create tenant email template", "tags": [ "Mail" ], "responses": { "200": { "description": "Tenant Email template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailTemplates", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateCreateInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/email-templates/{templateId}": { "get": { "summary": "Read tenant email template", "tags": [ "Mail" ], "responses": { "200": { "description": "Tenant Email template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EmailTemplatesByTemplateId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update tenant email template", "tags": [ "Mail" ], "responses": { "200": { "description": "Tenant Email template updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1EmailTemplatesByTemplateId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateUpdateInput" } } } }, "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } }, "delete": { "summary": "Delete tenant email template", "tags": [ "Mail" ], "responses": { "200": { "description": "Tenant Email template deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateDeleteEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1EmailTemplatesByTemplateId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" } ] } } }, "/api/v1/email-messages": { "get": { "summary": "List queued email messages", "tags": [ "Mail" ], "responses": { "200": { "description": "Cursor-paginated tenant Email messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessagePageEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EmailMessages", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/CommunicationMailListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create queued email message", "tags": [ "Mail" ], "responses": { "200": { "description": "Queued tenant Email message created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailMessages", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageCreateInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true } ] } } }, "/api/v1/email-messages/{messageId}": { "get": { "summary": "Read queued email message", "tags": [ "Mail" ], "responses": { "200": { "description": "Tenant Email message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EmailMessagesByMessageId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/email-messages/{messageId}/retry": { "post": { "summary": "Move failed or cancelled message back to queued", "tags": [ "Mail" ], "responses": { "200": { "description": "Failed or cancelled Email message queued again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailMessagesByMessageIdRetry", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/email-messages/{messageId}/cancel": { "post": { "summary": "Cancel queued or failed message", "tags": [ "Mail" ], "responses": { "200": { "description": "Queued or failed Email message cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailMessagesByMessageIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] } } }, "/api/v1/email-broadcasts/preview": { "post": { "summary": "Preview tenant-scoped broadcast audience", "tags": [ "Mail" ], "responses": { "200": { "description": "Masked Broadcast audience preview without writes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBroadcastPreviewEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "A selected Booking or Ticket audience feature is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailBroadcastsPreview", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "communication:read", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBroadcastInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [ "calendar.booking", "ticketing.checkout" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" }, { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "A selected Booking or Ticket audience feature is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/email-broadcasts": { "post": { "summary": "Queue tenant-scoped broadcast emails", "tags": [ "Mail" ], "responses": { "200": { "description": "Atomic tenant broadcast plan accepted or replayed with initial policy counts and current message states", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBroadcastResultEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "A selected Booking or Ticket audience feature is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Communication mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailBroadcasts", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "communication:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBroadcastInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [ "calendar.booking", "ticketing.checkout" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Communication mutation rate limit is exhausted" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "A selected Booking or Ticket audience feature is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "worker", "description": "The mail worker later claims and delivers queued messages", "conditional": true }, { "kind": "provider", "description": "A configured mail provider receives the message or callback state", "conditional": true }, { "kind": "webhook", "description": "Queues sanitized mail lifecycle Webhook deliveries", "conditional": true } ] }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/email-provider-events/{provider}": { "post": { "summary": "Receive signed delivery, bounce, complaint, and drop events from a mail provider", "tags": [ "Mail" ], "responses": { "200": { "description": "Signed provider event accepted idempotently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailProviderEventEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmailProviderEventsByProvider", "security": [ { "mailProviderSignature": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "providerSignature", "allowedPrincipals": [ "provider-signature" ], "credentialLocation": "signature-header", "csrfRequiredForCookieSession": false, "credentialName": "x-vsm-mail-signature" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailProviderEventInput" } } } }, "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "suppression", "description": "Bounce, complaint, and drop events create suppression state", "conditional": true } ] } } }, "/api/v1/seatmaps": { "get": { "summary": "List seat maps", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Cursor-paginated tenant SeatMaps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Seatmaps", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a draft-only seat map with server-owned lifecycle fields", "tags": [ "Seat Maps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapCreateInput" } } } }, "responses": { "200": { "description": "Created draft-only SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Seatmaps", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-create", "description": "Creates a tenant- and Location-bound v1 draft; lifecycle fields remain server-owned." } ] } } }, "/api/v1/seatmaps/{seatMapId}": { "get": { "summary": "Read seat map", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Tenant-scoped SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1SeatmapsBySeatMapId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update editable seat map fields without lifecycle mutation", "tags": [ "Seat Maps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapUpdateInput" } } } }, "responses": { "200": { "description": "Updated editable draft SeatMap fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1SeatmapsBySeatMapId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-update", "description": "Updates only editable draft fields after tenant Location and lifecycle checks." } ] } }, "delete": { "summary": "Permanently delete an unused draft seat map", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Permanent deletion result for an unused draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapDeletionEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1SeatmapsBySeatMapId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-delete", "description": "Permanently deletes only an unused draft with no operational or historical references." } ] } } }, "/api/v1/seatmaps/{seatMapId}/layout": { "put": { "summary": "Strictly replace a draft seat-map layout with optimistic concurrency protection", "tags": [ "Seat Maps" ], "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted current SeatMap.updatedAt value", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapLayoutDocument" } } } }, "responses": { "200": { "description": "Version-guarded draft SeatMap with replaced layout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1SeatmapsBySeatMapIdLayout", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-layout-replace", "description": "Strictly replaces the durable layout when If-Match still equals SeatMap.updatedAt." } ] } } }, "/api/v1/seatmaps/{seatMapId}/draft": { "post": { "summary": "Create next draft version of a seat map", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Next draft version and source SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapDraftVersionEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatmapsBySeatMapIdDraft", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-draft-version", "description": "Creates the next versioned draft while preserving the source lifecycle record." } ] } } }, "/api/v1/seatmaps/{seatMapId}/duplicate": { "post": { "summary": "Duplicate a seat map into an independent v1 draft", "tags": [ "Seat Maps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapDuplicateInput" } } } }, "responses": { "200": { "description": "Independent v1 draft duplicate and source SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapDuplicateEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatmapsBySeatMapIdDuplicate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-duplicate", "description": "Creates an independent v1 draft without offering, occupancy, publication, or audit links." } ] } } }, "/api/v1/seatmaps/{seatMapId}/publish": { "post": { "summary": "Publish seat map", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Validated published SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatmapsBySeatMapIdPublish", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-publish", "description": "Validates layout and linked pricing before persisting published status and timestamp." } ] } } }, "/api/v1/seatmaps/{seatMapId}/archive": { "post": { "summary": "Archive a seat map through the explicit lifecycle command", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Archived SeatMap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatmapsBySeatMapIdArchive", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "seatMapId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seatmap-archive", "description": "Archives the SeatMap only when no published TicketOffering references it." } ] } } }, "/api/v1/seatmap-analytics": { "get": { "summary": "Read scope-safe historical seat-map analytics", "tags": [ "Seat Maps" ], "parameters": [ { "name": "seatMapId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "scopeKind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" } }, { "name": "scopeKey", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Scope-safe historical SeatMap analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatmapAnalyticsEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1SeatmapAnalytics", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/seatmap-occupancy": { "get": { "summary": "Read exact operator occupancy for one seat-map scope", "tags": [ "Seat Maps" ], "parameters": [ { "name": "seatMapId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "scopeKind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" } }, { "name": "scopeKey", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Exact scope-selected SeatMap occupancy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatmapOccupancyEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1SeatmapOccupancy", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "public:read", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/seat-holds": { "post": { "summary": "Create or renew temporary seat hold", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Created or renewed operator SeatHold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldWorkflowEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatHolds", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldCreateInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seat-hold-create-or-renew", "description": "Expires stale Holds and atomically creates or renews the requested occupancy target." } ] } } }, "/api/v1/seat-holds/{holdToken}/assign": { "post": { "summary": "Convert active hold into a final seat assignment", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Final SeatAssignment and consumed Hold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldAssignmentEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatHoldsByHoldTokenAssign", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldAssignmentInput" } } } }, "parameters": [ { "name": "holdToken", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seat-assignment-create", "description": "Atomically creates the final assignment and marks the source Hold assigned or released." } ] } } }, "/api/v1/seat-holds/{holdToken}": { "delete": { "summary": "Release temporary seat hold", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Idempotent operator Hold-group release result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldReleaseEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1SeatHoldsByHoldToken", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "holdToken", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seat-hold-release", "description": "Releases every active unbound Hold in the token group and preserves history." } ] } } }, "/api/v1/seat-assignments": { "get": { "summary": "List final seat assignments", "tags": [ "Seat Maps" ], "responses": { "200": { "description": "Cursor-paginated final SeatAssignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentPageEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1SeatAssignments", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/seat-assignments/{assignmentId}": { "get": { "summary": "Read one tenant-bound final seat assignment", "tags": [ "Seat Maps" ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Tenant-scoped final SeatAssignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1SeatAssignmentsByAssignmentId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/seat-assignments/{assignmentId}/reassign": { "post": { "summary": "Atomically move an active seat assignment to a conflict-free target", "tags": [ "Seat Maps" ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentReassignInput" } } } }, "responses": { "200": { "description": "Reassigned SeatAssignment and audit evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatAssignmentsByAssignmentIdReassign", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seat-assignment-reassign", "description": "Atomically moves the active assignment and appends a PII-minimal audit event." } ] } } }, "/api/v1/seat-assignments/{assignmentId}/release": { "post": { "summary": "Atomically release an active seat assignment", "tags": [ "Seat Maps" ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentReleaseInput" } } } }, "responses": { "200": { "description": "Released SeatAssignment and audit evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatAssignmentCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1SeatAssignmentsByAssignmentIdRelease", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "seatmaps.studio", "features": [ "seatmaps.studio" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "seat-assignment-release", "description": "Atomically releases the active assignment and appends a PII-minimal audit event." } ] } } }, "/api/v1/events": { "get": { "summary": "List tenant events with stable instance identities", "tags": [ "Events" ], "responses": { "200": { "description": "Cursor page of tenant Events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Events", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024 } }, { "name": "q", "in": "query", "description": "Case-insensitive title substring, filtered before pagination", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "scheduled", "published", "archived" ] } } ] }, "post": { "summary": "Create event and assign stable IDs to every instance", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCreateInput" } } } }, "responses": { "200": { "description": "Created draft or scheduled Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Events", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event and stable EventInstance schedule" } ] } } }, "/api/v1/events/{eventId}": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read event with stable instance identities", "tags": [ "Events" ], "responses": { "200": { "description": "Tenant-scoped Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update explicit event fields and upsert instances by stable ID", "description": "PATCH injects no create defaults. Omitting instances preserves the schedule. Supplying instances atomically updates/creates by ID and removes only unreferenced omitted instances; this endpoint currently has no If-Match contract.", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventUpdateInput" } } } }, "responses": { "200": { "description": "Updated Event with stable instance identities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1EventsByEventId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event and stable EventInstance schedule" } ] } } }, "/api/v1/events/{eventId}/publish": { "post": { "summary": "Publish event after readiness validation", "tags": [ "Events" ], "responses": { "200": { "description": "Published Event and readiness checklist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPublishEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdPublish", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event and stable EventInstance schedule" }, { "kind": "webhook", "description": "Enqueues idempotent event.published Webhook deliveries", "conditional": true } ] } } }, "/api/v1/events/{eventId}/notify-change": { "post": { "summary": "Queue event-change notices for affected attendees", "tags": [ "Events" ], "responses": { "200": { "description": "Queued Event-change customer notices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventNoticeEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdNotifyChange", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventNoticeInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mail", "description": "Queues deduplicated Event-change messages for resolved recipients", "conditional": true }, { "kind": "webhook", "description": "Enqueues idempotent event.changed Webhook deliveries", "conditional": true } ] } } }, "/api/v1/events/{eventId}/cancel": { "post": { "summary": "Archive event and queue cancellation notices", "tags": [ "Events" ], "responses": { "200": { "description": "Archived Event and queued cancellation notices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventNoticeEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventNoticeInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event and stable EventInstance schedule" }, { "kind": "mail", "description": "Queues Event cancellation messages for resolved recipients", "conditional": true }, { "kind": "webhook", "description": "Enqueues idempotent event.cancelled Webhook deliveries", "conditional": true } ] } } }, "/api/v1/events/{eventId}/schedule-reminder": { "post": { "summary": "Queue event reminder broadcast", "tags": [ "Mail" ], "responses": { "200": { "description": "Atomically accepted or replayed Event reminder command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReminderEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdScheduleReminder", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReminderInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional tenant-bound UUID command key; unchanged intent replays without effects" } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mail", "description": "Atomically supersedes trusted predecessor plans, cancels queued reminders, and persists the accepted replacement; accepted replay has no new effects" }, { "kind": "webhook", "description": "Enqueues mail.queued Webhook deliveries", "conditional": true } ] } } }, "/api/v1/events/{eventId}/duplicate": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Duplicate an event as a fresh collision-safe draft", "tags": [ "Events" ], "responses": { "200": { "description": "Independent collision-safe Event draft duplicate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdDuplicate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event and stable EventInstance schedule" }, { "kind": "persistence", "description": "Copies durable lineup and media relationships when configured", "conditional": true } ] } } }, "/api/v1/events/{eventId}/alerts": { "get": { "summary": "Read Event alert audiences, Campaign history, analytics and automations", "tags": [ "Events", "Mail" ], "responses": { "200": { "description": "Event Alert workspace without recipient addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertWorkspaceEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventIdAlerts", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create an idempotent multi-channel Event alert Campaign", "tags": [ "Events", "Mail" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Created or replayed Event Alert Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertCampaignCreateEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdAlerts", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertCampaignInput" } } } }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Atomically stores Campaign, delivery, suppression, and EmailMessage state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "mail", "description": "Queues eligible Event Alert email deliveries", "conditional": true }, { "kind": "worker", "description": "Schedules or is reconciled by the bounded recurring Worker", "conditional": true } ] } } }, "/api/v1/events/{eventId}/alerts/audience-preview": { "post": { "summary": "Preview a consent and preference filtered Event alert audience", "tags": [ "Events", "Mail" ], "responses": { "200": { "description": "Masked and channel-aware Event Alert audience preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertAudiencePreviewEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdAlertsAudiencePreview", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertAudiencePreviewInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/events/{eventId}/alerts/{campaignId}/cancel": { "post": { "summary": "Cancel one queued or processing Event alert Campaign", "tags": [ "Events", "Mail" ], "responses": { "200": { "description": "Cancelled non-terminal Event Alert Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertCampaignEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdAlertsByCampaignIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "mail", "description": "Queues eligible Event Alert email deliveries", "conditional": true } ] } } }, "/api/v1/events/{eventId}/alert-automations/{offeringId}": { "put": { "summary": "Upsert a bounded low-inventory Event alert automation", "tags": [ "Events", "Mail", "Ticketing" ], "responses": { "200": { "description": "Upserted low-inventory Event Alert automation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertAutomationEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1EventsByEventIdAlertAutomationsByOfferingId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsAlertAutomationInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "worker", "description": "Schedules or is reconciled by the bounded recurring Worker", "conditional": true } ] } } }, "/api/v1/events/{eventId}/credits": { "get": { "summary": "Read tenant-scoped Event Credit accounts, ledger transactions and reconciliation", "tags": [ "Events", "Payments" ], "responses": { "200": { "description": "Sanitized Event Credit operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditOperatorWorkspaceEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "events.credits is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventIdCredits", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "event-credits:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "events.credits is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/events/{eventId}/credits/configuration": { "put": { "summary": "Configure currency, top-up bounds and post-event refunds", "tags": [ "Events", "Payments" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 96, "pattern": "^\".+\"$" } } ], "responses": { "200": { "description": "CAS-updated Event Credit configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditConfigurationEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "events.credits is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1EventsByEventIdCreditsConfiguration", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "event-credits:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditConfigurationInput" } } } }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "events.credits is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/credits/charges/confirm": { "post": { "summary": "Atomically claim one Event Credit token and transfer funds through tenant Stripe Connect", "tags": [ "Events", "Payments" ], "responses": { "200": { "description": "Consumed Event Credit authorization and charge result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditTransactionEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "events.credits is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdCreditsChargesConfirm", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "event-credits:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditChargeConfirmationInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "events.credits is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "provider", "description": "Calls the configured external provider with sanitized fail-closed handling", "conditional": true } ] } } }, "/api/v1/events/{eventId}/credits/reconciliation": { "post": { "summary": "Reconcile Event Credit ledger against Stripe and freeze debits above tolerance", "tags": [ "Events", "Payments", "Operations" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Event Credit ledger/provider reconciliation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsCreditReconciliationEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "events.credits is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdCreditsReconciliation", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "event-credits:write", "credentialName": "Authorization" }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "events.credits is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "provider", "description": "Calls the configured external provider with sanitized fail-closed handling", "conditional": true } ] } } }, "/api/v1/events/{eventId}/lineup": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read the tenant-scoped ordered event lineup", "tags": [ "Events" ], "responses": { "200": { "description": "Ordered tenant-scoped Event Line-up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsLineupEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventIdLineup", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "put": { "summary": "Replace the organizer and ordered event lineup", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsLineupReplaceInput" } } } }, "responses": { "200": { "description": "Atomically replaced Event Line-up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsLineupEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1EventsByEventIdLineup", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/media-branding": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read durable Event media, branding, and tenant templates", "tags": [ "Events" ], "responses": { "200": { "description": "Event media, branding, and template workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBrandingWorkspaceEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventIdMediaBranding", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/events/{eventId}/media": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Validate and durably upload Event media", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaUploadInput" } } } }, "responses": { "200": { "description": "Validated and persisted Event media asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdMedia", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "storage", "description": "Writes or deletes a tenant-partitioned Event media object", "conditional": true }, { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/media/{mediaId}": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update accessible Event media metadata and ordering", "tags": [ "Events" ], "responses": { "200": { "description": "Updated and reordered Event media metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1EventsByEventIdMediaByMediaId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaUpdateInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } }, "delete": { "summary": "Unlink Event media and schedule durable object cleanup", "tags": [ "Events" ], "responses": { "200": { "description": "Deleted Event media link with truthful cleanup state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaDeleteEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1EventsByEventIdMediaByMediaId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "storage", "description": "Writes or deletes a tenant-partitioned Event media object", "conditional": true }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "worker", "description": "Schedules or is reconciled by the bounded recurring Worker", "conditional": true } ] } } }, "/api/v1/events/{eventId}/branding": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Save a strict accessible Event branding theme", "tags": [ "Events" ], "responses": { "200": { "description": "Validated accessible Event branding theme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1EventsByEventIdBranding", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/branding-templates": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create a reusable tenant Event branding template", "tags": [ "Events" ], "responses": { "200": { "description": "Created reusable tenant branding template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingTemplateEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdBrandingTemplates", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingTemplateCreateInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/branding-templates/{templateId}": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update a tenant Event branding template", "tags": [ "Events" ], "responses": { "200": { "description": "Updated reusable tenant branding template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingTemplateEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1EventsByEventIdBrandingTemplatesByTemplateId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingTemplateUpdateInput" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } }, "delete": { "summary": "Delete a tenant Event branding template", "tags": [ "Events" ], "responses": { "200": { "description": "Deleted reusable tenant branding template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsDeletionEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1EventsByEventIdBrandingTemplatesByTemplateId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/branding-templates/{templateId}/apply": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Apply a tenant branding template to an Event", "tags": [ "Events" ], "responses": { "200": { "description": "Applied tenant branding template to Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsBrandingEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdBrandingTemplatesByTemplateIdApply", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/event-media/{eventId}/{mediaId}": { "get": { "summary": "Stream authenticated tenant Event media", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "200": { "description": "Private immutable Event media bytes", "content": { "image/jpeg": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } }, "image/png": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } }, "image/webp": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventMediaByEventIdByMediaId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/event-media/{eventId}/{mediaId}": { "get": { "summary": "Stream published or short-lived signed protected Event media", "tags": [ "Public" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "access", "in": "query", "required": false, "schema": { "type": "string", "minLength": 43, "maxLength": 512 } } ], "responses": { "200": { "description": "Published or signed protected Event media bytes", "content": { "image/jpeg": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } }, "image/png": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } }, "image/webp": { "schema": { "$ref": "#/components/schemas/EventOperationsMediaBinary" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicEventMediaByEventIdByMediaId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/events/{eventId}/secret-links": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List sanitized access-link lifecycle records", "tags": [ "Events" ], "responses": { "200": { "description": "Sanitized Event Secret Link history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsSecretLinkListEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventsByEventIdSecretLinks", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reconciles clock-expired links without exposing token hashes", "conditional": true } ] } }, "post": { "summary": "Create a protected event access link", "description": "Returns the raw key and complete URL exactly once. Only a SHA-256 hash and four-character fingerprint are persisted.", "tags": [ "Events" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsSecretLinkCreateInput" } } } }, "responses": { "200": { "description": "Created one-time raw Event Secret Link credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsSecretLinkCreateEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventsByEventIdSecretLinks", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/events/{eventId}/secret-links/{linkId}": { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Revoke one tenant- and event-scoped access link", "tags": [ "Events" ], "responses": { "200": { "description": "Idempotently revoked sanitized Event Secret Link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsSecretLinkEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1EventsByEventIdSecretLinksByLinkId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/event-organizers": { "get": { "summary": "List tenant event organizers", "tags": [ "Events" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bounded tenant Event-organizer result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrganizerListEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EventOrganizers", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a tenant event organizer", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrganizerCreateInput" } } } }, "responses": { "200": { "description": "Created tenant Event organizer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrganizerEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EventOrganizers", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event organizer" }, { "kind": "audit", "description": "Writes the corresponding tenant audit event" } ] } } }, "/api/v1/event-organizers/{organizerId}": { "parameters": [ { "name": "organizerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update a tenant event organizer", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrganizerUpdateInput" } } } }, "responses": { "200": { "description": "Updated tenant Event organizer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrganizerEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1EventOrganizersByOrganizerId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "organizerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event organizer" }, { "kind": "audit", "description": "Writes the corresponding tenant audit event" } ] } }, "delete": { "summary": "Delete an unused tenant event organizer", "tags": [ "Events" ], "responses": { "200": { "description": "Deleted unused Event organizer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDeletionEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Duplicate identity, state, schedule, or active reference conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Event, organizer, notice, recurrence, or query validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1EventOrganizersByOrganizerId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "organizerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Duplicate identity, state, schedule, or active reference conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Event, organizer, notice, recurrence, or query validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Deletes the organizer only when no Event references remain" }, { "kind": "audit", "description": "Writes the corresponding tenant audit event" } ] } } }, "/api/v1/artists": { "get": { "summary": "Search tenant Artists", "tags": [ "Events" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Tenant Artist catalog page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistListEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Artists", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "events:read", "credentialName": "Authorization" }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a tenant Artist", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistCreateInput" } } } }, "responses": { "200": { "description": "Created reusable tenant Artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Artists", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/artists/{artistId}": { "parameters": [ { "name": "artistId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update a tenant Artist", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistUpdateInput" } } } }, "responses": { "200": { "description": "Updated reusable tenant Artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1ArtistsByArtistId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "artistId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } }, "delete": { "summary": "Delete an unused tenant Artist", "tags": [ "Events" ], "responses": { "200": { "description": "Deleted unreferenced tenant Artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsDeletionEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1ArtistsByArtistId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "artistId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" } ] } } }, "/api/v1/artists/{artistId}/sync": { "parameters": [ { "name": "artistId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Queue controlled metadata sync for one Artist", "tags": [ "Events" ], "responses": { "200": { "description": "Queued fail-closed Artist metadata synchronization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOperationsArtistEnvelope" } } } }, "400": { "description": "Request cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authentication or session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or protected resource denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped Event resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Current lifecycle, duplicate identity, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Strict Event Operations validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or authenticated request limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1ArtistsByArtistIdSync", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "artistId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-event-operations-contract": "vsm-event-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or protected resource denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped Event resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Current lifecycle, duplicate identity, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Strict Event Operations validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or authenticated request limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, storage, Stripe, push, or Worker service is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped Event Operations state" }, { "kind": "audit", "description": "Writes a tenant-scoped immutable AuditEvent" }, { "kind": "worker", "description": "Schedules or is reconciled by the bounded recurring Worker", "conditional": true }, { "kind": "provider", "description": "Calls the configured external provider with sanitized fail-closed handling", "conditional": true } ] } } }, "/api/v1/ticket-offerings": { "get": { "summary": "List ticket offerings", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Cursor page of tenant Ticket offerings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingPageEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketOfferings", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024 } }, { "name": "eventId", "in": "query", "description": "Exact tenant-scoped event filter before pagination", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ] }, "post": { "summary": "Create ticket offering with optional canonical seat-map pricing", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingCreateInput" } } } }, "responses": { "200": { "description": "Created tenant Ticket offering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketOfferings", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped TicketOffering and ordered TicketTypes" }, { "kind": "audit", "description": "Appends immutable Ticket inventory-limit journal rows when limits change", "conditional": true } ] } } }, "/api/v1/ticket-offerings/{offeringId}": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one tenant-scoped ticket offering", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Tenant-scoped Ticket offering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketOfferingsByOfferingId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update one ticket offering with optimistic concurrency", "tags": [ "Ticketing" ], "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "If-Match", "in": "header", "required": true, "description": "Quoted TicketOffering.updatedAt value loaded by the client", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingUpdateInput" } } } }, "responses": { "200": { "description": "Version-guarded updated Ticket offering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfferingEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1TicketOfferingsByOfferingId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped TicketOffering and ordered TicketTypes" }, { "kind": "audit", "description": "Appends immutable Ticket inventory-limit journal rows when limits change", "conditional": true } ] } } }, "/api/v1/ticket-offerings/{offeringId}/inventory-adjustments": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "get": { "summary": "List immutable ticket inventory adjustments", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Bounded immutable inventory-limit history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInventoryAdjustmentListEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketOfferingsByOfferingIdInventoryAdjustments", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-promotions": { "get": { "summary": "List tenant ticket promotions", "tags": [ "Ticketing" ], "parameters": [ { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Bounded tenant Ticket promotion list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionListEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPromotions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a tenant ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Created draft Ticket promotion with optional one-time code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionWriteInput" } } } }, "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one tenant ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Tenant-scoped Ticket promotion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPromotionsByPromotionId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Replace an editable draft or paused promotion rule", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Replaced editable Ticket promotion rule with optional rotated code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1TicketPromotionsByPromotionId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionWriteInput" } } } }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/publish": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Publish a draft ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "publish Ticket promotion lifecycle result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdPublish", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/pause": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Pause an active ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "pause Ticket promotion lifecycle result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdPause", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/resume": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Resume a paused ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "resume Ticket promotion lifecycle result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdResume", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/end": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "End an active or paused ticket promotion", "tags": [ "Ticketing" ], "responses": { "200": { "description": "end Ticket promotion lifecycle result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdEnd", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped promotion rule and ordered TicketType constraints" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/invitations": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List masked promotion invitations", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Masked Ticket promotion invitation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationListEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPromotionsByPromotionIdInvitations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create and optionally queue one personal promotion invitation", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Created invitation with one-time token and optional queued delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationCreateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdInvitations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationCreateInput" } } } }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only encrypted recipient data, independent HMACs, masked display data, and invitation lifecycle" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" }, { "kind": "mail", "description": "Queues a transactional promotion invitation containing the one-time private URL", "conditional": true } ] } } }, "/api/v1/ticket-promotions/{promotionId}/invitations/{invitationId}/resend": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Queue a promotion invitation resend", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Queued Ticket promotion invitation resend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationResendEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdInvitationsByInvitationIdResend", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only encrypted recipient data, independent HMACs, masked display data, and invitation lifecycle" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" }, { "kind": "mail", "description": "Queues a transactional promotion invitation containing the one-time private URL", "conditional": false } ] } } }, "/api/v1/ticket-promotions/{promotionId}/invitations/{invitationId}/cancel": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Cancel a promotion invitation and revoke its active quote", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Cancelled Ticket promotion invitation and revoked active quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdInvitationsByInvitationIdCancel", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only encrypted recipient data, independent HMACs, masked display data, and invitation lifecycle" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" } ] } } }, "/api/v1/ticket-promotions/{promotionId}/imports": { "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List durable promotion invitation imports", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Durable Ticket promotion invitation import summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationImportListEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPromotionsByPromotionIdImports", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Import up to 5000 promotion invitation recipients", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Completed bounded Ticket promotion invitation import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationImportEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPromotionsByPromotionIdImports", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPromotionInvitationImportInput" } } } }, "parameters": [ { "name": "promotionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists only encrypted recipient data, independent HMACs, masked display data, and invitation lifecycle" }, { "kind": "audit", "description": "Appends immutable tenant-scoped promotion lifecycle evidence" }, { "kind": "worker", "description": "The bounded maintenance worker queues accepted pending invitations", "conditional": true } ] } } }, "/api/v1/ticket-queues/{offeringId}": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read tenant ticket queue configuration, metrics, entries, and events", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Tenant-scoped Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketQueuesByOfferingId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "put": { "summary": "Create or update bounded ticket queue configuration", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueConfigurationInput" } } } }, "responses": { "200": { "description": "Configured Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "putApiV1TicketQueuesByOfferingId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-queues/{offeringId}/activate": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Activate a configured ticket queue", "tags": [ "Ticketing" ], "responses": { "200": { "description": "activate Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketQueuesByOfferingIdActivate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-queues/{offeringId}/pause": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Pause new ticket queue admissions", "tags": [ "Ticketing" ], "responses": { "200": { "description": "pause Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketQueuesByOfferingIdPause", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-queues/{offeringId}/resume": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Resume a paused ticket queue", "tags": [ "Ticketing" ], "responses": { "200": { "description": "resume Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketQueuesByOfferingIdResume", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-queues/{offeringId}/end": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "End a ticket queue and remove pre-checkout entries", "tags": [ "Ticketing" ], "responses": { "200": { "description": "end Ticket queue operator workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspaceEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketQueuesByOfferingIdEnd", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-queues/{offeringId}/entries/{entryId}": { "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Remove one mutable tenant-bound ticket queue entry", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Terminal sanitized Ticket queue entry state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueRemoveEntryEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1TicketQueuesByOfferingIdEntriesByEntryId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/v1/ticket-refunds": { "get": { "summary": "List tenant ticket refunds", "tags": [ "Ticketing" ], "parameters": [ { "name": "orderId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Newest tenant-scoped sanitized Ticket refunds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundListEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketRefunds", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create and submit an idempotent Stripe ticket refund", "tags": [ "Ticketing" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundCreateInput" } } } }, "responses": { "200": { "description": "Submitted idempotent Ticket refund and replay state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketRefunds", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped refund, allocation, batch, batch-order, dispute and Ticket/order state" }, { "kind": "provider", "description": "Submits one idempotent Stripe refund and reconciles only confirmed provider state" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket financial events" } ] } } }, "/api/v1/ticket-refunds/preview": { "post": { "summary": "Preview a server-authoritative ticket refund", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundPreviewInput" } } } }, "responses": { "200": { "description": "Authoritative side-effect-free Ticket refund preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundPreviewEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketRefundsPreview", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-refunds/{refundId}": { "parameters": [ { "name": "refundId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one tenant ticket refund", "tags": [ "Ticketing" ], "responses": { "200": { "description": "One tenant-scoped sanitized Ticket refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketRefundsByRefundId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "refundId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-refund-batches/preview": { "post": { "summary": "Preview an event or offering mass refund", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundBatchPreviewInput" } } } }, "responses": { "200": { "description": "Authoritative side-effect-free Event offering refund batch preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundBatchPreviewEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketRefundBatchesPreview", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-refund-batches": { "post": { "summary": "Queue an idempotent mass refund batch", "tags": [ "Ticketing" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundBatchCreateInput" } } } }, "responses": { "200": { "description": "Queued idempotent Event refund batch and replay state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundBatchMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketRefundBatches", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped refund, allocation, batch, batch-order, dispute and Ticket/order state" }, { "kind": "worker", "description": "Makes a queued refund batch available to the bounded Stripe refund Worker" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket financial events" } ] } } }, "/api/v1/ticket-refund-batches/{batchId}": { "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read mass refund progress", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Tenant-scoped Event refund batch and per-order state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketRefundBatchEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketRefundBatchesByBatchId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-disputes": { "get": { "summary": "List ticket payment disputes", "tags": [ "Ticketing" ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "underReview", "won", "lost" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Tenant-scoped payment dispute deadline inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketDisputeListEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketDisputes", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-disputes/{disputeId}/acknowledge": { "parameters": [ { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Mark an open ticket dispute under review", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketDisputeAcknowledgeInput" } } } }, "responses": { "200": { "description": "Acknowledged nonterminal payment dispute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketDisputeEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role, API scope, or tenant denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, order, offering, refund, batch, or dispute was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Refund selection, amount, reason, note, state, or limit is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketDisputesByDisputeIdAcknowledge", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-finance-contract": "vsm-ticket-finance-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role, API scope, or tenant denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, order, offering, refund, batch, or dispute was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Order, Ticket, active dispute, idempotency, refund balance, batch, or terminal state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Refund selection, amount, reason, note, state, or limit is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Stripe, or required finance runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped refund, allocation, batch, batch-order, dispute and Ticket/order state" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket financial events" } ] } } }, "/api/v1/analytics-overview": { "get": { "summary": "Read tenant-scoped booking, revenue, utilization, conversion, check-in, and seat analytics", "tags": [ "Analytics" ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "comparePrevious", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "web", "phone", "walkIn", "internal", "ticket" ], "default": "all" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } } ], "responses": { "200": { "description": "Exact PII-free analytics read model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingAnalyticsOverviewEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AnalyticsOverview", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingAnalyticsQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/analytics-overview/export": { "get": { "summary": "Export the filtered analytics overview as UTF-8 CSV", "tags": [ "Analytics" ], "responses": { "200": { "description": "Filtered analytics metrics and daily rows", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ReportingCsvArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AnalyticsOverviewExport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "comparePrevious", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "web", "phone", "walkIn", "internal", "ticket" ], "default": "all" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingAnalyticsQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/growth-funnel": { "get": { "summary": "Read tenant-scoped booking, revenue, utilization, conversion, check-in, and seat analytics", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "serviceId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } } ], "responses": { "200": { "description": "Evidence-based F09 cohort and event funnel without contact data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrowthFunnelEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1GrowthFunnel", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/GrowthFunnelQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/growth-funnel/export": { "get": { "summary": "Export the filtered analytics overview as UTF-8 CSV", "tags": [ "Analytics" ], "responses": { "200": { "description": "Formula-safe F09 funnel export under the same contract", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ReportingCsvArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1GrowthFunnelExport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "serviceId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/GrowthFunnelQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/next-actions": { "get": { "summary": "Read tenant-scoped booking, revenue, utilization, conversion, check-in, and seat analytics", "tags": [ "Analytics" ], "responses": { "200": { "description": "F10 rule-based next actions with numbers, window and work-context link; read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextActionsEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1NextActions", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/holiday-imports": { "post": { "summary": "Preview, apply or roll back statutory public holidays for a calendar", "tags": [ "Communication" ], "responses": { "200": { "description": "F13 computed statutory holiday preview, optimistic apply or rollback of source-ID calendar exceptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1HolidayImports", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1" } }, "/api/v1/campaign-provider-report": { "get": { "summary": "Read tenant-scoped Campaign delivery and provider reliability reporting", "tags": [ "Analytics" ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "inApp", "push" ] } } ], "responses": { "200": { "description": "Exact PII-free Campaign/provider report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingCampaignProviderReportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CampaignProviderReport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingCampaignQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/campaign-provider-report/export": { "get": { "summary": "Export filtered Campaign delivery and provider reporting as UTF-8 CSV", "tags": [ "Analytics" ], "responses": { "200": { "description": "Filtered formula-safe Campaign/provider report", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ReportingCsvArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1CampaignProviderReportExport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "inApp", "push" ] } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingCampaignQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/exports": { "get": { "summary": "List tenant-scoped durable export jobs", "tags": [ "Exports" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Tenant-scoped durable export jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingExportJobListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Exports", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create or replay an idempotent durable CSV export job", "tags": [ "Exports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingCreateExportJobInput" } } } }, "responses": { "200": { "description": "Exact idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingExportJobMutationEnvelope" } } } }, "202": { "description": "Durable export job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingExportJobMutationEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Exports", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates one tenant-scoped idempotent ExportJob" }, { "kind": "audit", "description": "Writes a PII-minimal export.job.created audit event" }, { "kind": "worker", "description": "Makes the bounded export job eligible for Worker processing" } ] } } }, "/api/v1/exports/{exportJobId}": { "get": { "summary": "Read one tenant-scoped durable export job", "tags": [ "Exports" ], "parameters": [ { "name": "exportJobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "One tenant-scoped export job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingExportJobEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1ExportsByExportJobId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/exports/{exportJobId}/download": { "get": { "summary": "Download and audit a completed tenant-scoped export artifact", "tags": [ "Exports" ], "parameters": [ { "name": "exportJobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Integrity-verified private export artifact", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ReportingCsvArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "410": { "description": "The private export artifact has expired", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1ExportsByExportJobIdDownload", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 410, "codes": [ "CONFLICT" ], "description": "The private export artifact has expired" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Increments the tenant-scoped download counter after integrity verification" }, { "kind": "audit", "description": "Writes export.artifact.downloaded without storage keys or PII" } ] } } }, "/api/v1/ticket-payout-report": { "get": { "summary": "Read currency-separated ticket payout and fee reconciliation", "tags": [ "Ticketing" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Currency-separated book/provider payout report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingTicketPayoutReportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPayoutReport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingTicketPayoutQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-payout-report/export": { "get": { "summary": "Export the filtered payout reconciliation as safe UTF-8 CSV", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Formula-safe Offering and provider-payout rows", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ReportingCsvArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPayoutReportExport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "eventId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/ReportingTicketPayoutQueryInput" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-payout-reconciliations": { "post": { "summary": "Queue an idempotent tenant-owned Stripe payout reconciliation", "tags": [ "Ticketing" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingPayoutReconciliationInput" } } } }, "responses": { "200": { "description": "Queued reconciliation or idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingPayoutReconciliationMutationEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketPayoutReconciliations", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates one tenant-scoped idempotent reconciliation run" }, { "kind": "worker", "description": "Makes the run eligible for bounded Stripe settlement and payout reconciliation" }, { "kind": "external-provider", "description": "The Worker conditionally reads the tenant Stripe Connect provider state", "conditional": true } ] } } }, "/api/v1/ticket-payout-reconciliations/{runId}": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one tenant-scoped payout reconciliation run", "tags": [ "Ticketing" ], "responses": { "200": { "description": "One tenant-scoped sanitized reconciliation run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingPayoutReconciliationEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketPayoutReconciliationsByRunId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-orders": { "post": { "summary": "Create ticket order with server-side pricing and inventory checks", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Pending operator-created Ticket order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOrderCreateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketOrders", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOrderCreateInput" } } } }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reserves inventory and persists the pending TicketOrder atomically" }, { "kind": "persistence", "description": "Links and renews the exact seat-hold group for the order", "conditional": true } ] } } }, "/api/v1/ticket-orders/{orderId}": { "get": { "summary": "Read ticket order, optionally with issued tickets and seat assignments", "tags": [ "Ticketing" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tickets" ] } } ], "responses": { "200": { "description": "Ticket order or issued-ticket detail when include=tickets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOrderReadEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketOrdersByOrderId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-orders/{orderId}/checkout": { "post": { "summary": "Create Stripe Checkout Session for a pending ticket order", "tags": [ "Ticketing" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCheckoutInput" } } } }, "responses": { "200": { "description": "Idempotent Stripe Checkout handoff for a pending Ticket order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCheckoutEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketOrdersByOrderIdCheckout", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Links and renews the exact seat-hold group for the order", "conditional": true }, { "kind": "provider", "description": "Creates one idempotent Stripe Checkout Session and stores its safe identifiers" } ] } } }, "/api/v1/ticket-orders/{orderId}/fulfill": { "post": { "summary": "Fulfill ticket order and queue ticket mail", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Assignment-first recoverable paid Ticket fulfillment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketFulfillmentEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketOrdersByOrderIdFulfill", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Repairs Tickets and seat assignments before completing the paid order" }, { "kind": "mail", "description": "Queues one idempotent Ticket confirmation message", "conditional": true }, { "kind": "webhook", "description": "Enqueues one idempotent ticket.order.completed delivery", "conditional": true } ] } } }, "/api/v1/ticket-orders/{orderId}/resend-mail": { "post": { "summary": "Queue another ticket confirmation mail for a completed order", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Queued replacement mail for an issued Ticket order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketMailEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketOrdersByOrderIdResendMail", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "mail", "description": "Queues a fresh Ticket confirmation for the completed order" } ] } } }, "/api/v1/tickets/{ticketId}/check-in": { "post": { "summary": "Redeem ticket once for staff check-in", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Atomically redeemed Ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketsByTicketIdCheckIn", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCheckInInput" } } } }, "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Atomically redeems an accepted Ticket and persists one tenant-scoped scan event" }, { "kind": "audit", "description": "Appends immutable privacy-safe Ticket scan history" }, { "kind": "webhook", "description": "Queues one idempotent ticket.checked_in delivery", "conditional": true } ] } } }, "/api/v1/tickets/{ticketId}/no-show": { "post": { "summary": "Mark a valid ticket as no-show for event-day operations", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Ticket marked as an operational no-show", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Marks or clears the operational no-show timestamp without invalidating a late-arriving Ticket" } ] }, "operationId": "postApiV1TicketsByTicketIdNoShow", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" } } }, "/api/v1/tickets/{ticketId}/undo-no-show": { "post": { "summary": "Remove the event-day no-show marker from a valid ticket", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Operational no-show marker cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Marks or clears the operational no-show timestamp without invalidating a late-arriving Ticket" } ] }, "operationId": "postApiV1TicketsByTicketIdUndoNoShow", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "tickets:write", "credentialName": "Authorization" } } }, "/api/v1/ticket-check-ins": { "get": { "summary": "List immutable tenant ticket scan history", "tags": [ "Ticketing" ], "parameters": [ { "name": "offeringId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "live", "offline" ] } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "accepted", "alreadyRedeemed", "invalidCode", "invalidStatus", "offlinePackageExpired", "offlinePackageRevoked" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Newest bounded privacy-safe Ticket scan history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketScanListEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketCheckIns", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Atomically scan one live ticket code", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketLiveScanInput" } } } }, "responses": { "200": { "description": "Idempotent atomic live Ticket scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCheckInCommandEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketCheckIns", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Atomically redeems an accepted Ticket and persists one tenant-scoped scan event" }, { "kind": "audit", "description": "Appends immutable privacy-safe Ticket scan history" }, { "kind": "webhook", "description": "Queues one idempotent ticket.checked_in delivery", "conditional": true } ] } } }, "/api/v1/ticket-check-ins/offline-packages": { "post": { "summary": "Create a device-bound hashed offline verification package", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfflinePackageCreateInput" } } } }, "responses": { "200": { "description": "Device-bound hashed offline package without raw redeemable codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfflinePackageEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketCheckInsOfflinePackages", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists or revokes a device-bound package containing hashes but no raw access or QR codes" }, { "kind": "audit", "description": "Appends immutable privacy-safe Ticket scan history" } ] } } }, "/api/v1/ticket-check-ins/offline-sync": { "post": { "summary": "Idempotently synchronize hashed offline scan events", "tags": [ "Ticketing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfflineSyncInput" } } } }, "responses": { "200": { "description": "Ordered idempotent results for 1-200 offline scans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfflineSyncEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketCheckInsOfflineSync", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Atomically redeems an accepted Ticket and persists one tenant-scoped scan event" }, { "kind": "audit", "description": "Appends immutable privacy-safe Ticket scan history" }, { "kind": "webhook", "description": "Queues one idempotent ticket.checked_in delivery", "conditional": true } ] } } }, "/api/v1/ticket-check-ins/{packageId}/revoke": { "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Idempotently revoke one tenant offline scan package", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Idempotently revoked tenant offline package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOfflinePackageEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Ticket state, changed idempotency payload, or device/location binding conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or offline Ticket package exceeds its bound", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1TicketCheckInsByPackageIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "packageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Ticket state, changed idempotency payload, or device/location binding conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or offline Ticket package exceeds its bound" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists or revokes a device-bound package containing hashes but no raw access or QR codes" }, { "kind": "audit", "description": "Appends immutable privacy-safe Ticket scan history" } ] } } }, "/api/v1/offline-operations": { "get": { "summary": "Read tenant-scoped offline devices and sanitized operation history", "tags": [ "Offline Operations" ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "deviceId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "200": { "description": "Sanitized device workspace and newest operation history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineOperationsWorkspaceEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1OfflineOperations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "offline:read", "credentialName": "Authorization" }, "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/OfflineOperationsWorkspaceQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "none" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Enroll a location-bound offline device and return its secret once", "tags": [ "Offline Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineDeviceCreateInput" } } } }, "responses": { "200": { "description": "Device enrollment with one-time secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineDeviceEnrollmentEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "none" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates or changes a tenant- and Location-bound offline device" }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/offline-operations/{deviceId}": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one tenant-scoped offline device", "tags": [ "Offline Operations" ], "responses": { "200": { "description": "One tenant-scoped sanitized offline device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineDeviceSummaryEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1OfflineOperationsByDeviceId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "offline:read", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "none" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/offline-operations/{deviceId}/rotate": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Rotate one active device secret and return the replacement once", "tags": [ "Offline Operations" ], "responses": { "200": { "description": "Rotated device enrollment with one-time replacement secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineDeviceEnrollmentEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperationsByDeviceIdRotate", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "none" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates or changes a tenant- and Location-bound offline device" }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/offline-operations/{deviceId}/revoke": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Revoke device, ticket packages, and credit reservations atomically", "tags": [ "Offline Operations" ], "responses": { "200": { "description": "Idempotently revoked device and dependent offline material", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineDeviceSummaryEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperationsByDeviceIdRevoke", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "none" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates or changes a tenant- and Location-bound offline device" }, { "kind": "persistence", "description": "Revokes active Ticket packages and Event-credit reservations atomically" }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/offline-operations/{deviceId}/credit-reservations": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Reserve one customer event-credit amount for a bounded offline window", "tags": [ "Offline Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineCreditReservationCreateInput" } } } }, "responses": { "200": { "description": "Device-bound Event-credit reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineCreditReservationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The domain feature required by this operation is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperationsByDeviceIdCreditReservations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The domain feature required by this operation is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reserves wallet cents under a serializable transaction" }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/offline-operations/{deviceId}/credit-reservations/{reservationId}/revoke": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reservationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Release a device-bound event-credit reservation", "tags": [ "Offline Operations" ], "responses": { "200": { "description": "Released Event-credit reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineCreditReservationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The domain feature required by this operation is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperationsByDeviceIdCreditReservationsByReservationIdRevoke", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "reservationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "events.credits", "features": [ "events.credits" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The domain feature required by this operation is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Revokes the tenant/device-bound credit reservation" }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/offline-operations/{deviceId}/sync": { "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-VSM-Offline-Device-Secret", "in": "header", "required": true, "schema": { "type": "string", "minLength": 40, "maxLength": 128 } } ], "post": { "summary": "Verify and replay signed ticket, coupon, and event-credit operations exactly once", "tags": [ "Offline Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineOperationsSyncInput" } } } }, "responses": { "200": { "description": "Ordered exactly-once results for 1-200 signed operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineOperationsSyncEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator/API credential or offline device secret is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The domain feature required by this operation is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or revoked device denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Device state, wallet balance, time window, sequence, or replay conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body or signed operation batch exceeds the configured limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, device signing, or required provider runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1OfflineOperationsByDeviceIdSync", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "offline:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "X-VSM-Offline-Device-Secret", "in": "header", "required": true, "schema": { "type": "string", "minLength": 40, "maxLength": 128, "pattern": "^vsm_od_[A-Za-z0-9_-]+$" } } ], "x-vsm-offline-operations-contract": "vsm-offline-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": null, "features": [ "ticketing.checkout", "loyalty.programs", "events.credits" ], "mode": "operationKind" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or offline device secret is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The domain feature required by this operation is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or revoked device denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location, device, Event, Customer, or reservation was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Device state, wallet balance, time window, sequence, or replay conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body or signed operation batch exceeds the configured limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, TTL, amount, envelope, signature, payload, or batch is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, device signing, or required provider runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Claims and finalizes immutable exactly-once operation journal rows" }, { "kind": "domain-command", "description": "Delegates each entry to Ticket, Coupon, or Event-credit workflow", "conditional": true }, { "kind": "provider", "description": "Submits or resumes one idempotent Event-credit Stripe charge", "conditional": true }, { "kind": "webhook", "description": "Queues ticket.checked_in for an accepted Ticket scan", "conditional": true }, { "kind": "audit", "description": "Appends privacy-safe device or operation audit evidence" } ] } } }, "/api/v1/assistant/templates": { "get": { "summary": "List assistant prompt templates", "tags": [ "Assistant" ], "responses": { "200": { "description": "Localized operator Assistant templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantTemplateListEnvelope" } } } }, "401": { "description": "Operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Assistant task, locale, tone, length, prompt, or context is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AssistantTemplates", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-assistant-contract": "vsm-assistant-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session is missing or invalid" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Assistant task, locale, tone, length, prompt, or context is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ] } }, "/api/v1/assistant/usage": { "get": { "summary": "Read assistant usage and latest audit runs", "tags": [ "Assistant" ], "responses": { "200": { "description": "Monthly Assistant quota and latest sanitized runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsageEnvelope" } } } }, "401": { "description": "Operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "assistant.llm is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AssistantUsage", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-assistant-contract": "vsm-assistant-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "assistant.llm", "features": [ "assistant.llm" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "assistant.llm is inactive for the tenant" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/assistant/suggestions": { "post": { "summary": "Generate entitlement-gated, audited assistant suggestions", "tags": [ "Assistant" ], "responses": { "200": { "description": "Audited Assistant suggestions and updated usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSuggestionEnvelope" } } } }, "401": { "description": "Operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "assistant.llm is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Assistant task, locale, tone, length, prompt, or context is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "IP, tenant/user, or monthly Assistant quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AssistantSuggestions", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSuggestionInput" } } } }, "x-vsm-assistant-contract": "vsm-assistant-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "assistant.llm", "features": [ "assistant.llm" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "assistant.llm is inactive for the tenant" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Assistant task, locale, tone, length, prompt, or context is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "IP, tenant/user, or monthly Assistant quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes IP and tenant/user Assistant quota" }, { "kind": "external-provider", "description": "Calls the configured OpenAI Responses endpoint or returns the deterministic fallback", "conditional": true }, { "kind": "persistence", "description": "Persists a tenant-scoped, prompt-hashed Assistant run and bounded output preview" } ] } } }, "/api/v1/embed/sessions": { "get": { "summary": "List embed sessions", "tags": [ "Integrations" ], "responses": { "200": { "description": "Token-free tenant Embed session page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmbedSessionListEnvelope" } } } }, "401": { "description": "Operator session or signed unsubscribe token is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "embeds.website is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role denies Embed session access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Origin, expiry, pagination, or unsubscribe input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence or unsubscribe signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1EmbedSessions", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or signed unsubscribe token is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "embeds.website is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role denies Embed session access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Origin, expiry, pagination, or unsubscribe input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence or unsubscribe signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create capped embed session", "tags": [ "Integrations" ], "responses": { "200": { "description": "Created website embed key or legacy session with one-time token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmbedSessionCreatedEnvelope" } } } }, "400": { "description": "Malformed JSON request body", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or signed unsubscribe token is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "embeds.website is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role denies Embed session access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Origin, expiry, pagination, or unsubscribe input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence or unsubscribe signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1EmbedSessions", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmbedSessionCreateInput" } } } }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Malformed JSON request body" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or signed unsubscribe token is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "embeds.website is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role denies Embed session access" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Origin, expiry, pagination, or unsubscribe input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence or unsubscribe signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes one tenant-scoped Embed session or Email suppression" } ] } } }, "/api/v1/embed/sessions/{sessionId}/revoke": { "post": { "summary": "Idempotently revoke a website embed key", "tags": [ "Integrations" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "200": { "description": "Idempotently revoked website embed key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmbedSessionRevokedEnvelope" } } } }, "401": { "description": "Operator session or signed unsubscribe token is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "embeds.website is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role denies Embed session access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped website embed key was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence or unsubscribe signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or signed unsubscribe token is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "embeds.website is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role denies Embed session access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped website embed key was not found" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence or unsubscribe signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Sets revokedAt on one tenant-scoped website embed key and writes a security audit event", "conditional": true } ] }, "operationId": "postApiV1EmbedSessionsBySessionIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/integration-credentials": { "get": { "summary": "List API credentials without secret hashes", "tags": [ "Integrations" ], "responses": { "200": { "description": "Cursor-paginated credential list without bearer hashes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialPageEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1IntegrationCredentials", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/IntegrationCredentialListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create API credential and return the secret once", "tags": [ "Integrations" ], "responses": { "200": { "description": "Created credential and one-time bearer secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialOneTimeSecretEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1IntegrationCredentials", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialCreateInput" } } } }, "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped credential lifecycle state and only a SHA-256 bearer hash" }, { "kind": "audit", "description": "Appends a PII-minimal immutable credential lifecycle audit event" } ] } } }, "/api/v1/integration-credentials/{credentialId}": { "get": { "summary": "Read one API credential without its secret hash", "tags": [ "Integrations" ], "responses": { "200": { "description": "Tenant-scoped credential without bearer hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialResultEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1IntegrationCredentialsByCredentialId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update API credential name, scopes or request quota", "tags": [ "Integrations" ], "responses": { "200": { "description": "Updated active API credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialResultEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1IntegrationCredentialsByCredentialId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialUpdateInput" } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped credential lifecycle state and only a SHA-256 bearer hash" }, { "kind": "audit", "description": "Appends a PII-minimal immutable credential lifecycle audit event" } ] } } }, "/api/v1/integration-credentials/{credentialId}/rotate": { "post": { "summary": "Rotate an API credential and return the new secret once", "tags": [ "Integrations" ], "responses": { "200": { "description": "Rotated credential and one-time replacement secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialOneTimeSecretEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1IntegrationCredentialsByCredentialIdRotate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialRotateInput" } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped credential lifecycle state and only a SHA-256 bearer hash" }, { "kind": "audit", "description": "Appends a PII-minimal immutable credential lifecycle audit event" } ] } } }, "/api/v1/integration-credentials/{credentialId}/revoke": { "post": { "summary": "Idempotently revoke an API credential", "tags": [ "Integrations" ], "responses": { "200": { "description": "Idempotently revoked credential and replay state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialRevokeEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1IntegrationCredentialsByCredentialIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant-scoped credential lifecycle state and only a SHA-256 bearer hash" }, { "kind": "audit", "description": "Appends a PII-minimal immutable credential lifecycle audit event" } ] } } }, "/api/v1/integration-credentials/{credentialId}/usage": { "get": { "summary": "Read PII-minimal usage and lifecycle audit for an API credential", "tags": [ "Integrations" ], "responses": { "200": { "description": "PII-minimal credential lifecycle and quota audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCredentialUsageEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1IntegrationCredentialsByCredentialIdUsage", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/webhooks": { "get": { "summary": "List webhook endpoints without secret hashes", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Cursor-paginated webhook endpoints without secrets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointPageEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Webhooks", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebhookEndpointListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create webhook endpoint with HMAC signing secret", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Created encrypted HMAC webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1Webhooks", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateInput" } } } }, "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped endpoint with signing-secret hash and AES-GCM ciphertext" } ] } } }, "/api/v1/webhooks/{webhookId}": { "get": { "summary": "Read webhook endpoint without secret hash", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Tenant-scoped webhook endpoint without secrets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebhooksByWebhookId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Update webhook URL, events or active state", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Updated webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1WebhooksByWebhookId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateInput" } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped endpoint with signing-secret hash and AES-GCM ciphertext" } ] } } }, "/api/v1/webhooks/{webhookId}/rotate": { "post": { "summary": "Replace and encrypt a webhook signing secret", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook endpoint with rotated encrypted secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookMutationEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebhooksByWebhookIdRotate", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRotateInput" } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped endpoint with signing-secret hash and AES-GCM ciphertext" } ] } } }, "/api/v1/webhooks/{webhookId}/test": { "post": { "summary": "Queue a real worker-signed webhook test delivery", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Queued real worker-signed webhook test delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebhooksByWebhookIdTest", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestInput" } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists the tenant-scoped endpoint with signing-secret hash and AES-GCM ciphertext" }, { "kind": "persistence", "description": "Persists or requeues a tenant-scoped immutable webhook delivery record" }, { "kind": "worker", "description": "The compiled worker resolves and pins a public target, signs the raw payload, delivers it, and records outcome/retry state", "conditional": true }, { "kind": "provider", "description": "Performs the signed outbound HTTP callback", "conditional": true } ] } } }, "/api/v1/webhook-deliveries": { "get": { "summary": "List tenant webhook delivery history", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Filtered cursor-paginated webhook delivery history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPageEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebhookDeliveries", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "endpointId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebhookDeliveryListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/webhook-deliveries/{deliveryId}": { "get": { "summary": "Read one tenant webhook delivery", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Tenant-scoped webhook delivery detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebhookDeliveriesByDeliveryId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/webhook-deliveries/{deliveryId}/retry": { "post": { "summary": "Retry a non-delivered webhook delivery", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Non-delivered webhook delivery queued for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryRetryEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "api.webhooks is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or submitted legacy secret denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped credential, endpoint, or delivery was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebhookDeliveriesByDeliveryIdRetry", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "webhooks:write", "credentialName": "Authorization" }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-integration-webhook-contract": "vsm-integration-webhook-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "api.webhooks", "features": [ "api.webhooks" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "api.webhooks is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or submitted legacy secret denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped credential, endpoint, or delivery was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Credential lifecycle, inactive/legacy endpoint, or delivered retry conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scope, quota, URL, event, secret, cursor, or mutation input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, webhook secret encryption, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists or requeues a tenant-scoped immutable webhook delivery record" }, { "kind": "worker", "description": "The compiled worker resolves and pins a public target, signs the raw payload, delivers it, and records outcome/retry state", "conditional": true }, { "kind": "provider", "description": "Performs the signed outbound HTTP callback", "conditional": true } ] } } }, "/api/v1/admin": { "get": { "summary": "Combined platform-admin overview", "tags": [ "Admin" ], "responses": { "200": { "description": "Combined Platform Admin overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminOverviewEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1Admin", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads readiness and release evidence" } ] } } }, "/api/v1/admin/overview": { "get": { "summary": "Combined platform-admin overview", "tags": [ "Admin" ], "responses": { "200": { "description": "Combined Platform Admin overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminOverviewEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminOverview", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads readiness and release evidence" } ] } } }, "/api/v1/admin/tenants": { "get": { "summary": "List tenant summaries for platform support", "tags": [ "Admin" ], "responses": { "200": { "description": "Cursor page of Platform tenant summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminTenantListEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Cursor, support-case, or feature-override input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminTenants", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/PlatformAdminFoundationCursorQuery" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Cursor, support-case, or feature-override input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/admin/tenants/{tenantId}/owner-invite": { "post": { "summary": "Invite the first Owner of a tenant without a joined Owner", "tags": [ "Admin" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Issued, re-issued or idempotently replayed first-Owner invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminTenantOwnerInviteEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target account, assignment, session, tenant, or credential was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required Redis lock is not configured or not reachable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminTenantOwnerInviteInput" } } } }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target account, assignment, session, tenant, or credential was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required Redis lock is not configured or not reachable" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a pending Owner membership without a joined user; withdraws another pending Owner invitation of the same tenant", "conditional": true }, { "kind": "auth-token", "description": "Issues the regular hashed seven-day invite token accepted by POST /api/v1/auth/invite/accept", "conditional": true }, { "kind": "mail", "description": "Queues the tenant-scoped teamInvite mail", "conditional": true }, { "kind": "audit", "description": "Writes tenant.owner_invite.created with admin actor, reason and invitee email digest", "conditional": true } ] }, "operationId": "postApiV1AdminTenantsByTenantIdOwnerInvite", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/audit-events": { "get": { "summary": "List PII-minimized audit events", "tags": [ "Admin" ], "responses": { "200": { "description": "Cursor page of PII-minimized Platform audit events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminAuditEventListEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Cursor, support-case, or feature-override input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminAuditEvents", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/PlatformAdminFoundationCursorQuery" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Cursor, support-case, or feature-override input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/admin/support-cases": { "get": { "summary": "List support cases", "tags": [ "Admin" ], "responses": { "200": { "description": "Cross-tenant Support SLA and audit queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleListEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminSupportCases", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] } } ], "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/AdminSupportCaseListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create support case and audit event", "tags": [ "Admin" ], "responses": { "200": { "description": "Created Platform support case and immutable audit event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminSupportCaseCreateEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Cursor, support-case, or feature-override input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminSupportCases", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminSupportCaseCreateInput" } } } }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Cursor, support-case, or feature-override input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a Platform support case" }, { "kind": "audit", "description": "Writes the support-case creation event" }, { "kind": "pii-minimization", "description": "Stores only a requester email digest", "conditional": true } ] } } }, "/api/v1/admin/support-cases/{caseId}": { "get": { "summary": "Read cross-tenant support case audit detail", "tags": [ "Admin", "Support" ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Cross-tenant Support case audit detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseLifecycleEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminSupportCasesByCaseId", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/feature-overrides": { "get": { "summary": "List feature overrides", "tags": [ "Admin" ], "responses": { "200": { "description": "Cursor page of tenant Feature overrides", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminFeatureOverrideListEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Cursor, support-case, or feature-override input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminFeatureOverrides", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/PlatformAdminFoundationCursorQuery" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Cursor, support-case, or feature-override input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create feature override and audit event", "tags": [ "Admin" ], "responses": { "200": { "description": "Created Feature override, audit event, and entitlement preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminFeatureOverrideCreateEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target tenant was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Cursor, support-case, or feature-override input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminFeatureOverrides", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminFeatureOverrideCreateInput" } } } }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target tenant was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Cursor, support-case, or feature-override input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a tenant-scoped Feature override" }, { "kind": "audit", "description": "Writes the override creation event" }, { "kind": "entitlement", "description": "Changes effective tenant entitlements immediately" } ] } } }, "/api/v1/admin/release-checklist": { "get": { "summary": "Read runtime readiness, M9 release checklist, and machine-readable readiness report", "tags": [ "Admin" ], "responses": { "200": { "description": "Runtime readiness, release checklist, and stable machine report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAdminReleaseReadinessEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform Admin capability or CSRF policy denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminReleaseChecklist", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-foundation-contract": "vsm-platform-admin-foundation-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform Admin capability or CSRF policy denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads dependencies, environment, and evidence artifacts" } ] } } }, "/api/v1/admin/privacy/consent-policy": { "get": { "summary": "Read the versioned global privacy consent policy", "tags": [ "Admin", "Privacy" ], "responses": { "200": { "description": "Current versioned global consent policy state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentAdminStateEnvelope" } } } }, "401": { "description": "An authenticated Platform Admin session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated Platform Admin session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminPrivacyConsentPolicy", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/privacy/consent-policy/draft": { "put": { "summary": "Save the CAS-protected privacy consent policy draft", "tags": [ "Admin", "Privacy" ], "responses": { "200": { "description": "CAS-protected consent policy draft state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentAdminStateEnvelope" } } } }, "401": { "description": "An authenticated Platform Admin session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Draft revision, publish, or rollback state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The policy, decision, locale, source, or version is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentDraftInput" } } } }, "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated Platform Admin session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Draft revision, publish, or rollback state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The policy, decision, locale, source, or version is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates or revises the single global draft" }, { "kind": "audit", "description": "Appends a privacy consent policy audit event" } ] }, "operationId": "putApiV1AdminPrivacyConsentPolicyDraft", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/privacy/consent-policy/publish": { "post": { "summary": "Publish an immutable privacy consent policy version", "tags": [ "Admin", "Privacy" ], "responses": { "200": { "description": "Published immutable consent policy version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentAdminStateEnvelope" } } } }, "401": { "description": "An authenticated Platform Admin session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Draft revision, publish, or rollback state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The policy, decision, locale, source, or version is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentPublishInput" } } } }, "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated Platform Admin session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Draft revision, publish, or rollback state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The policy, decision, locale, source, or version is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Supersedes the current version and publishes the draft" }, { "kind": "audit", "description": "Appends a privacy consent publication audit event" } ] }, "operationId": "postApiV1AdminPrivacyConsentPolicyPublish", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/privacy/consent-policy/rollback": { "post": { "summary": "Publish a new version from historic consent policy content", "tags": [ "Admin", "Privacy" ], "responses": { "200": { "description": "New monotonic version based on historic policy content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentAdminStateEnvelope" } } } }, "401": { "description": "An authenticated Platform Admin session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Draft revision, publish, or rollback state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The policy, decision, locale, source, or version is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentRollbackInput" } } } }, "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated Platform Admin session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Draft revision, publish, or rollback state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The policy, decision, locale, source, or version is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Publishes a new version without mutating policy history" }, { "kind": "audit", "description": "Appends a privacy consent rollback audit event" } ] }, "operationId": "postApiV1AdminPrivacyConsentPolicyRollback", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/privacy/consent-policy/audit": { "get": { "summary": "Read the bounded privacy consent policy audit history", "tags": [ "Admin", "Privacy" ], "responses": { "200": { "description": "Bounded consent policy audit history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyConsentPolicyAuditEnvelope" } } } }, "401": { "description": "An authenticated Platform Admin session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated Platform Admin session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminPrivacyConsentPolicyAudit", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/role-assignments": { "get": { "summary": "List scoped platform-role assignments", "tags": [ "Admin", "Security" ], "parameters": [ { "name": "includeRevoked", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "role", "in": "query", "schema": { "$ref": "#/components/schemas/PlatformAdminRole" } }, { "name": "search", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Bounded global Platform role-assignment inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformRoleAssignmentListEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.roleAssignments.read", "operationId": "getApiV1AdminRoleAssignments", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/AdminPlatformRoleAssignmentListQuery" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Grant or revive a scoped platform-role assignment", "tags": [ "Admin", "Security" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformRoleGrantInput" } } } }, "responses": { "200": { "description": "Granted or revived Platform role assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformRoleGrantEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target account, assignment, session, tenant, or credential was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.roleAssignments.write", "operationId": "postApiV1AdminRoleAssignments", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target account, assignment, session, tenant, or credential was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revocation", "description": "Revokes every target-account session before the grant" }, { "kind": "persistence", "description": "Creates or revives a scoped Platform role assignment" }, { "kind": "audit", "description": "Writes platform_role.granted atomically with the role mutation" } ] } } }, "/api/v1/admin/role-assignments/{assignmentId}/revoke": { "post": { "summary": "Revoke a platform-role assignment", "tags": [ "Admin", "Security" ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformRoleRevokeInput" } } } }, "responses": { "200": { "description": "Idempotently revoked Platform role assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformRoleRevokeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target account, assignment, session, tenant, or credential was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.roleAssignments.write", "operationId": "postApiV1AdminRoleAssignmentsByAssignmentIdRevoke", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target account, assignment, session, tenant, or credential was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revocation", "description": "Revokes every target-account session before the role mutation", "conditional": true }, { "kind": "persistence", "description": "Revokes the assignment while preserving the final Super Admin guard", "conditional": true }, { "kind": "audit", "description": "Writes platform_role.revoked atomically with the role mutation", "conditional": true } ] } } }, "/api/v1/admin/operations-console": { "get": { "summary": "Read the sanitized platform system-control snapshot", "tags": [ "Admin", "Security", "Operations" ], "responses": { "200": { "description": "Sanitized vsm-platform-operations-console-v1 snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformOperationsConsoleEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capabilities": [ "admin.security.read", "admin.quality.read", "admin.credentials.read" ], "operationId": "getApiV1AdminOperationsConsole", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence-read", "description": "Reads bounded audit, session, quality, credential, tenant, and Webhook state" }, { "kind": "provider-configuration-read", "description": "Reports provider configuration presence without returning values" } ] } } }, "/api/v1/admin/security-sessions/{sessionId}/revoke": { "post": { "summary": "Revoke another platform session and audit the command", "tags": [ "Admin", "Security" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformOperationsCommandInput" } } } }, "responses": { "200": { "description": "Idempotently revoked another Platform session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformSessionRevokeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target account, assignment, session, tenant, or credential was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required Prisma persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.security.write", "operationId": "postApiV1AdminSecuritySessionsBySessionIdRevoke", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target account, assignment, session, tenant, or credential was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required Prisma persistence is unavailable" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session-revocation", "description": "Revokes the selected non-current AuthSession", "conditional": true }, { "kind": "audit", "description": "Writes AuthSession and Platform security audit events without session material", "conditional": true } ] } } }, "/api/v1/admin/quality-review/run": { "post": { "summary": "Run and audit the platform data-quality review", "tags": [ "Admin", "Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformOperationsCommandInput" } } } }, "responses": { "200": { "description": "Current Platform quality findings and aggregate audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformQualityReviewEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.quality.write", "operationId": "postApiV1AdminQualityReviewRun", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence-read", "description": "Recomputes bounded integrity findings across operational records" }, { "kind": "audit", "description": "Writes platform_quality.reviewed with aggregate counts only" } ] } } }, "/api/v1/admin/credentials/{credentialId}/rotate": { "post": { "summary": "Rotate a tenant API key from the platform console", "tags": [ "Admin", "Security" ], "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformOperationsCommandInput" } } } }, "responses": { "200": { "description": "Rotated API credential with one-time bearer secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlatformCredentialRotateEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Target account, assignment, session, tenant, or credential was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.credentials.write", "operationId": "postApiV1AdminCredentialsByCredentialIdRotate", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Target account, assignment, session, tenant, or credential was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "credential-rotation", "description": "Replaces the API public key and secret hash and invalidates the old bearer" }, { "kind": "one-time-secret", "description": "Returns the new bearer secret exactly once" }, { "kind": "audit", "description": "Writes integration.credential.rotated_by_platform without secret material" } ] } } }, "/api/v1/admin/worker-queues": { "get": { "summary": "Inspect Worker heartbeat, queue counts, pause state, and 24-hour metrics", "tags": [ "Admin", "Operations" ], "responses": { "200": { "description": "PII-minimized vsm-worker-queue-ops-v1 overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerQueueOverviewEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminWorkerQueues", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.read", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads bounded Worker heartbeat, BullMQ counts, pause state, and 24-hour metrics" } ] } } }, "/api/v1/admin/worker-queues/{queueKey}/failed-jobs": { "get": { "summary": "List sanitized retained failed jobs for one Worker queue", "tags": [ "Admin", "Operations" ], "parameters": [ { "name": "queueKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Sanitized bounded vsm-worker-queue-failures-v1 page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerFailedJobPageEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminWorkerQueuesByQueueKeyFailedJobs", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-query-schema": { "$ref": "#/components/schemas/AdminWorkerFailurePageQuery" }, "x-vsm-required-capability": "admin.worker.read", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads retained BullMQ failed-state metadata without payload values or stacks" } ] } } }, "/api/v1/admin/worker-queues/{queueKey}/pause": { "post": { "summary": "Pause a registered Worker queue and write an Admin audit event", "tags": [ "Admin", "Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited idempotent Worker queue pause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerQueueCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerQueuesByQueueKeyPause", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "queue-command", "description": "Pauses the selected shared BullMQ queue", "conditional": true }, { "kind": "audit", "description": "Writes worker_queue.paused with aggregate state only" } ] } } }, "/api/v1/admin/worker-queues/{queueKey}/resume": { "post": { "summary": "Resume a registered Worker queue and write an Admin audit event", "tags": [ "Admin", "Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited idempotent Worker queue resume", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerQueueCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerQueuesByQueueKeyResume", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "queue-command", "description": "Resumes the selected shared BullMQ queue", "conditional": true }, { "kind": "audit", "description": "Writes worker_queue.resumed with aggregate state only" } ] } } }, "/api/v1/admin/worker-queues/{queueKey}/failed-jobs/{jobId}/retry": { "post": { "summary": "Retry one retained failed Worker job and write an Admin audit event", "tags": [ "Admin", "Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited retry of exactly one retained failed job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerQueueCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Job state or bounded schedule-command lock conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerQueuesByQueueKeyFailedJobsByJobIdRetry", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Job state or bounded schedule-command lock conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "queue-command", "description": "Moves the selected authoritative failed job back to its original queue" }, { "kind": "audit", "description": "Writes worker_job.retried without payload or failure text" } ] } } }, "/api/v1/admin/worker-schedules": { "get": { "summary": "Inspect the canonical recurring Worker schedule registry and runtime metrics", "tags": [ "Admin", "Operations" ], "responses": { "200": { "description": "PII-minimized vsm-worker-schedule-ops-v1 registry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleOverviewEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminWorkerSchedules", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.read", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "runtime-read", "description": "Reads canonical UTC schedules, BullMQ registration, pause markers, and bounded metrics" } ] } } }, "/api/v1/admin/worker-schedules/{scheduleId}/pause": { "post": { "summary": "Pause one recurring Worker schedule and retain that state across restarts", "tags": [ "Admin", "Operations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited idempotent Worker schedule pause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Job state or bounded schedule-command lock conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerSchedulesByScheduleIdPause", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Job state or bounded schedule-command lock conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "schedule-registration", "description": "Persists the pause marker and removes the exact BullMQ scheduler", "conditional": true }, { "kind": "audit", "description": "Writes worker_schedule.paused with aggregate state only" } ] } } }, "/api/v1/admin/worker-schedules/{scheduleId}/resume": { "post": { "summary": "Repair and resume one recurring Worker schedule", "tags": [ "Admin", "Operations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited idempotent Worker schedule resume", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Job state or bounded schedule-command lock conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerSchedulesByScheduleIdResume", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Job state or bounded schedule-command lock conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "schedule-registration", "description": "Repairs the exact BullMQ scheduler and removes the pause marker", "conditional": true }, { "kind": "audit", "description": "Writes worker_schedule.resumed with aggregate state only" } ] } } }, "/api/v1/admin/worker-schedules/{scheduleId}/run-now": { "post": { "summary": "Enqueue one idempotent immediate run of a recurring Worker workflow", "tags": [ "Admin", "Operations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleRunNowInput" } } } }, "responses": { "200": { "description": "Audited idempotent immediate schedule run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerSchedulesByScheduleIdRunNow", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "dedupe", "description": "Writes a SHA-256-keyed bounded command marker without retaining the raw idempotency key" }, { "kind": "queue-command", "description": "Enqueues at most one immediate job with the canonical processor and payload contract", "conditional": true }, { "kind": "audit", "description": "Writes worker_schedule.run_now with aggregate state only" } ] } } }, "/api/v1/admin/worker-schedules/{scheduleId}/catch-up": { "post": { "summary": "Enqueue a bounded idempotent catch-up batch for missed UTC schedule slots", "tags": [ "Admin", "Operations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerCommandInput" } } } }, "responses": { "200": { "description": "Audited bounded idempotent schedule catch-up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Job state or bounded schedule-command lock conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Redis or BullMQ is unavailable within the bounded timeout", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminWorkerSchedulesByScheduleIdCatchUp", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Job state or bounded schedule-command lock conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Redis or BullMQ is unavailable within the bounded timeout" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "dedupe", "description": "Writes bounded per-slot dedupe markers and advances the durable catch-up cursor", "conditional": true }, { "kind": "queue-command", "description": "Enqueues only missing canonical schedule slots within the seven-day lookback", "conditional": true }, { "kind": "audit", "description": "Writes worker_schedule.catch_up with aggregate state only" } ] } } }, "/api/v1/privacy/export": { "get": { "summary": "Generate a tenant-scoped owner data export", "tags": [ "Privacy" ], "responses": { "200": { "description": "Complete tenant-scoped, secret-redacted portability snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPrivacyExportEnvelope" } } } }, "401": { "description": "An authenticated tenant session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant Owner role or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant context or requested resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing tenant data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1PrivacyExport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-privacy-data-rights-contract": "vsm-privacy-data-rights-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant Owner role or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant context or requested resource was not found" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing tenant data" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reads every tenant-owned page without a fixed 500-row truncation" }, { "kind": "audit", "description": "Appends privacy.export.generated with resource counts" } ] } } }, "/api/v1/privacy/export-request": { "post": { "summary": "Create a privacy export support request", "tags": [ "Privacy" ], "responses": { "200": { "description": "Accepted tenant data-export support request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPrivacyRequestEnvelope" } } } }, "401": { "description": "An authenticated tenant session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant Owner role or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant context or requested resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The reason, contact e-mail or metadata is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing tenant data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1PrivacyExportRequest", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPrivacyRequestInput" } } } }, "x-vsm-privacy-data-rights-contract": "vsm-privacy-data-rights-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant Owner role or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant context or requested resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The reason, contact e-mail or metadata is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing tenant data" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a tenant-scoped medium-priority Support Case with hashed requester e-mail" }, { "kind": "audit", "description": "Appends privacy.export.requested" } ] } } }, "/api/v1/privacy/deletion-request": { "post": { "summary": "Create a privacy deletion support request", "tags": [ "Privacy" ], "responses": { "200": { "description": "Accepted tenant deletion/legal-review request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPrivacyRequestEnvelope" } } } }, "401": { "description": "An authenticated tenant session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant Owner role or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant context or requested resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The reason, contact e-mail or metadata is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing tenant data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1PrivacyDeletionRequest", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPrivacyRequestInput" } } } }, "x-vsm-privacy-data-rights-contract": "vsm-privacy-data-rights-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "An authenticated tenant session is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant Owner role or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant context or requested resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The reason, contact e-mail or metadata is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing tenant data" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a tenant-scoped high-priority Support Case with hashed requester e-mail" }, { "kind": "audit", "description": "Appends privacy.deletion.requested" } ] } } }, "/api/public/email/unsubscribe": { "post": { "summary": "One-click public email unsubscribe endpoint", "tags": [ "Public" ], "responses": { "200": { "description": "Created or reused active Email suppression", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmailUnsubscribeEnvelope" } } } }, "400": { "description": "Malformed JSON request body", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator session or signed unsubscribe token is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Origin, expiry, pagination, or unsubscribe input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public unsubscribe rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence or unsubscribe signing secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicEmailUnsubscribe", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeEmailUnsubscribeInput" } } } }, "x-vsm-edge-contract": "vsm-edge-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Malformed JSON request body" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or signed unsubscribe token is invalid" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Origin, expiry, pagination, or unsubscribe input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public unsubscribe rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence or unsubscribe signing secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public unsubscribe rate-limit entry" }, { "kind": "persistence", "description": "Writes one tenant-scoped Embed session or Email suppression" } ] } } }, "/api/public/venues/{tenantSlug}/{locationSlug}": { "get": { "summary": "Read one active published venue profile", "tags": [ "Public", "Venues" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "Exact active immutable direct Venue Profile snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVenueProfileEnvelope" } } } }, "404": { "description": "Tenant-scoped Location or active published profile was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicVenuesByTenantSlugByLocationSlug", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-venue-profile-contract": "vsm-venue-profile-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location or active published profile was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public-read rate-limit entry", "conditional": true } ] } } }, "/api/public/ticket-transfers/{token}": { "get": { "summary": "Read a sanitized high-entropy token-scoped ticket-transfer invitation", "tags": [ "Public", "Ticketing" ], "responses": { "200": { "description": "Masked signed-token Ticket transfer handoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountPublicTicketTransferEnvelope" } } } }, "404": { "description": "The tenant, Customer, Booking, Ticket, or transfer was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded Customer or signed-token request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private account or provider details", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, public origin, mail, or provider configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicTicketTransfersByToken", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "path", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "x-vsm-customer-account-contract": "vsm-customer-account-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant, Customer, Booking, Ticket, or transfer was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded Customer or signed-token request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private account or provider details" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, public origin, mail, or provider configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Lazily marks an overdue pending transfer expired", "conditional": true } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/calendar": { "get": { "summary": "Public calendar data for direct pages and embeds", "tags": [ "Public" ], "responses": { "200": { "description": "Active Location-scoped Calendar page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCalendarEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicByTenantSlugByLocationSlugCalendar", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "calendarId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/availability": { "get": { "summary": "Server-side public calendar slot availability", "tags": [ "Public" ], "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "calendarId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "partySize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } } ], "responses": { "200": { "description": "Server-calculated Booking availability for one date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCalendarAvailabilityEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicByTenantSlugByLocationSlugAvailability", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/bookings": { "post": { "summary": "Create public booking with capacity and mail workflow", "tags": [ "Public" ], "responses": { "200": { "description": "Created pending public Booking with workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCreateEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the public JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicByTenantSlugByLocationSlugBookings", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCreateInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the public JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true }, { "kind": "persistence", "description": "Writes tenant-scoped Booking or Waitlist state" }, { "kind": "audit", "description": "Writes a PII-minimal public lifecycle audit event" }, { "kind": "mail", "description": "Queues transactional Booking mail when the workflow requires it", "conditional": true }, { "kind": "webhook", "description": "Queues subscribed Booking webhook deliveries", "conditional": true } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/waitlist": { "post": { "summary": "Join a ranked slot-bound public waitlist", "tags": [ "Public" ], "responses": { "200": { "description": "Accepted ranked Waitlist entry; newly created entries include a one-time management token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistCreateEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the public JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicByTenantSlugByLocationSlugWaitlist", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistCreateInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the public JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true }, { "kind": "persistence", "description": "Writes tenant-scoped Booking or Waitlist state" }, { "kind": "audit", "description": "Writes a PII-minimal public lifecycle audit event" } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/waitlist/{entryId}/cancel": { "post": { "summary": "Cancel a public waitlist entry with its management token", "tags": [ "Public" ], "responses": { "200": { "description": "Cancelled mutable Waitlist entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistCancelEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the public JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicByTenantSlugByLocationSlugWaitlistByEntryIdCancel", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistCancelInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the public JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true }, { "kind": "persistence", "description": "Writes tenant-scoped Booking or Waitlist state" }, { "kind": "audit", "description": "Writes a PII-minimal public lifecycle audit event" } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/waitlist/{entryId}/claim": { "post": { "summary": "Cancel a public waitlist entry with its management token", "tags": [ "Public" ], "responses": { "200": { "description": "F20 group-call claim: confirmed Booking if the whole party still fits; replay returns the same Booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistClaimEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the public JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicByTenantSlugByLocationSlugWaitlistByEntryIdClaim", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWaitlistCancelInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the public JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true }, { "kind": "persistence", "description": "Writes tenant-scoped Booking or Waitlist state" } ] } } }, "/api/public/{tenantSlug}/{locationSlug}/events": { "get": { "summary": "Public published events for direct pages and embeds", "tags": [ "Public" ], "responses": { "200": { "description": "Published public Events for one exact tenant Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEventListEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicByTenantSlugByLocationSlugEvents", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "locationSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/{tenantSlug}/privacy/consent-policy": { "get": { "summary": "Read the current published privacy consent policy", "tags": [ "Public", "Privacy" ], "responses": { "200": { "description": "Current published public consent policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPrivacyConsentPolicyEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public consent request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public consent request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiPublicByTenantSlugPrivacyConsentPolicy", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/{tenantSlug}/privacy/consent-decision": { "get": { "summary": "Read the current anonymous privacy consent decision", "tags": [ "Public", "Privacy" ], "responses": { "200": { "description": "Current subject-scoped consent decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPrivacyConsentDecisionStateEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public consent request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "vsm_privacy_subject", "in": "cookie", "required": false, "schema": { "type": "string", "minLength": 64, "maxLength": 1024 } } ], "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public consent request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "cookie", "description": "Issues an opaque signed HttpOnly subject cookie", "conditional": true } ] }, "operationId": "getApiPublicByTenantSlugPrivacyConsentDecision", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } }, "put": { "summary": "Append an anonymous privacy consent decision", "tags": [ "Public", "Privacy" ], "responses": { "200": { "description": "Append-only normalized public consent decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPrivacyConsentDecisionEnvelope" } } } }, "403": { "description": "Platform privacy capability or same-origin policy denied access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant or requested policy version was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The policy, decision, locale, source, or version is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The bounded public consent request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "The operation failed without exposing private consent data", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or signing configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPrivacyConsentDecisionInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "vsm_privacy_subject", "in": "cookie", "required": false, "schema": { "type": "string", "minLength": 64, "maxLength": 1024 } } ], "x-vsm-privacy-consent-contract": "vsm-privacy-consent-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform privacy capability or same-origin policy denied access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant or requested policy version was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The policy, decision, locale, source, or version is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The bounded public consent request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "The operation failed without exposing private consent data" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or signing configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Appends the normalized tenant-scoped consent decision" }, { "kind": "audit", "description": "Appends a privacy-safe decision audit event" }, { "kind": "cookie", "description": "Issues an opaque signed HttpOnly subject cookie", "conditional": true } ] }, "operationId": "putApiPublicByTenantSlugPrivacyConsentDecision", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/{tenantSlug}/events/{eventSlug}": { "get": { "summary": "Public published event detail with location and tickets", "tags": [ "Public" ], "responses": { "200": { "description": "Direct published Event landing-page detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEventDetailEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicByTenantSlugEventsByEventSlug", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "eventSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/events/secret/{secretSlug}": { "get": { "summary": "Resolve a protected event using a one-time-issued raw key", "description": "Query parameter key is required. A successful page/API open atomically consumes one configured usage; invalid, expired, exhausted, revoked, or mismatched links all fail closed as not found.", "tags": [ "Public" ], "parameters": [ { "name": "secretSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "X-VSM-Event-Secret", "in": "header", "required": true, "schema": { "type": "string", "minLength": 32, "maxLength": 256 } } ], "responses": { "200": { "description": "Resolved unlisted or private direct Event link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSecretEventEnvelope" } } } }, "401": { "description": "Authentication or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Event, organizer, tenant, location, or direct link was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or authenticated API quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL or runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicEventsSecretBySecretSlug", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "header", "csrfRequiredForCookieSession": false, "credentialName": "X-VSM-Event-Secret" }, "x-vsm-event-contract": "vsm-event-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authentication or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Event, organizer, tenant, location, or direct link was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or authenticated API quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL or runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Atomically consumes one allowed use of the signed Event link" } ] } } }, "/api/public/tickets/seat-holds": { "post": { "summary": "Create or extend a public ticket seat-hold group", "tags": [ "Public" ], "responses": { "200": { "description": "Created or extended public ticket SeatHold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsSeatHolds", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold", "description": "Creates or renews an offering-bound Hold after public Event, Location, Embed, and availability checks." } ] } } }, "/api/public/tickets/seat-holds/group": { "post": { "summary": "Atomically hold a validated public ticket seat group", "tags": [ "Public" ], "responses": { "200": { "description": "Atomically created public ticket SeatHold group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldGroupEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldGroupInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold-group", "description": "Validates one server-owned ticket and price category, then persists every requested Hold atomically under one token or persists none." } ] }, "operationId": "postApiPublicTicketsSeatHoldsGroup", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/tickets/seat-holds/best-available": { "post": { "summary": "Rank and atomically hold the best available public ticket seats", "tags": [ "Public" ], "responses": { "200": { "description": "Deterministically ranked and atomically held best available group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldBestAvailableEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldBestAvailableInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold-best-available", "description": "Ranks only available contiguous seats in one server-owned ticket and price category, then persists the selected Hold group atomically." } ] }, "operationId": "postApiPublicTicketsSeatHoldsBestAvailable", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/tickets/seat-holds/renew": { "post": { "summary": "Renew an unbound public ticket seat-hold group", "tags": [ "Public" ], "responses": { "200": { "description": "Renewed unbound public Hold group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldRenewEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsSeatHoldsRenew", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldCommandInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold-renew", "description": "Atomically extends every active unbound Hold in the offering-scoped token group." } ] } } }, "/api/public/tickets/seat-holds/release": { "post": { "summary": "Release an unbound public ticket seat-hold group", "tags": [ "Public" ], "responses": { "200": { "description": "Idempotent public Hold-group release result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldReleaseEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsSeatHoldsRelease", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldCommandInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold-release", "description": "Releases every active unbound Hold in the offering-scoped token group and preserves history." } ] } } }, "/api/public/tickets/seat-holds/change": { "post": { "summary": "Safely replace one public ticket seat hold", "tags": [ "Public" ], "responses": { "200": { "description": "Replacement Hold and released predecessor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldChangeEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsSeatHoldsChange", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatHoldChangeInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-hold-change", "description": "Acquires the replacement before atomically releasing the one unbound predecessor Hold." } ] } } }, "/api/public/tickets/seat-waitlist/join": { "post": { "summary": "Join a sold-out reserved-seat waitlist", "tags": [ "Public" ], "responses": { "200": { "description": "Created or deduplicated ranked reserved-seat waitlist entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistJoinEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistJoinInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-waitlist-join", "description": "Validates tenant, offering, event instance, ticket type, current inventory, adjacent-seat availability and accessibility before persisting a ranked entry." } ] }, "operationId": "postApiPublicTicketsSeatWaitlistJoin", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/tickets/seat-waitlist/status": { "post": { "summary": "Read a managed reserved-seat waitlist entry", "tags": [ "Public" ], "responses": { "200": { "description": "Bearer-scoped waitlist status without customer PII", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistEntryEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistManageInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-waitlist-status", "description": "Reads only the manage-token-scoped entry and lazily expires an elapsed offer and its unbound Holds.", "conditional": true } ] }, "operationId": "postApiPublicTicketsSeatWaitlistStatus", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "manageToken" } } }, "/api/public/tickets/seat-waitlist/cancel": { "post": { "summary": "Cancel a managed reserved-seat waitlist entry", "tags": [ "Public" ], "responses": { "200": { "description": "Cancelled waitlist entry and released unbound offer Holds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistEntryEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistManageInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-waitlist-cancel", "description": "Cancels the manage-token-scoped entry idempotently and releases its unbound atomic Hold group." } ] }, "operationId": "postApiPublicTicketsSeatWaitlistCancel", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "manageToken" } } }, "/api/public/tickets/seat-waitlist/accept": { "post": { "summary": "Accept an active reserved-seat waitlist offer", "tags": [ "Public" ], "responses": { "200": { "description": "Idempotently accepted active offer with authoritative price and existing Hold group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistAcceptEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Required tenant feature entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, occupancy, idempotency, or concurrency conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request, layout, scope, or seat target validation failed", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Caller exceeded the bounded request rate", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal error", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistAcceptInput" } } } }, "x-vsm-seatmap-contract": "vsm-seatmap-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "Required tenant feature entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, protected-event, or embed-origin check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, occupancy, idempotency, or concurrency conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request, layout, scope, or seat target validation failed" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Caller exceeded the bounded request rate" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal error" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "public-ticket-seat-waitlist-accept", "description": "Validates the hashed offer bearer, expiry, scope, price and complete active Hold group, then records acceptance without creating a second Hold." } ] }, "operationId": "postApiPublicTicketsSeatWaitlistAccept", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "offerToken" } } }, "/api/public/tickets/promotions": { "get": { "summary": "List currently visible public ticket promotions", "tags": [ "Public" ], "parameters": [ { "name": "tenantSlug", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "offeringId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "secretSlug", "in": "query", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 160 } }, { "name": "X-VSM-Event-Access-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 32, "maxLength": 256 } } ], "responses": { "200": { "description": "Currently visible public Ticket promotions for one offering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketPromotionListEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicTicketsPromotions", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/tickets/promotions/quote": { "post": { "summary": "Reserve an idempotent server-priced ticket promotion quote", "tags": [ "Public" ], "responses": { "200": { "description": "Idempotent signed server-priced Ticket promotion quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketPromotionQuoteEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsPromotionsQuote", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketPromotionQuoteInput" } } } }, "x-vsm-ticket-promotion-contract": "vsm-ticket-promotion-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, promotion, invitation, import, or linked resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, uniqueness, assignment, budget, quote, or pricing conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Promotion, invitation, import, selector, cart, or pricing input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, mail, secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Locks promotion budgets and reserves one signed ten-minute server-priced quote idempotently" } ] } } }, "/api/public/tickets/queue": { "get": { "summary": "Read safe public ticket queue state", "tags": [ "Public" ], "parameters": [ { "name": "tenantSlug", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "offeringId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "secretSlug", "in": "query", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "X-VSM-Event-Access-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 32, "maxLength": 256 } } ], "responses": { "200": { "description": "Public Offering-scoped Ticket queue state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueuePublicStateEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicTicketsQueue", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "trafficSignal", "description": "Increments a short-lived bounded Redis traffic counter for optional automatic activation", "conditional": true } ] } } }, "/api/public/tickets/queue/join": { "post": { "summary": "Join or restore a browser-bound public ticket queue entry", "tags": [ "Public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueJoinInput" } } } }, "responses": { "200": { "description": "One-time browser-bound queue session and entry state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueJoinEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsQueueJoin", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "session", "description": "Stores only session/browser/IP HMACs and optional encrypted/masked buyer e-mail state" }, { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/public/tickets/queue/status": { "post": { "summary": "Poll a browser-bound ticket queue entry", "tags": [ "Public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueSessionInput" } } } }, "responses": { "200": { "description": "Current browser-bound Ticket queue entry state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueEntryPublicStateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsQueueStatus", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "sessionToken" }, "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/public/tickets/queue/checkout": { "post": { "summary": "Idempotently start checkout for an admitted queue entry", "tags": [ "Public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueSessionInput" } } } }, "responses": { "200": { "description": "Checkout-active browser-bound Ticket queue entry state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketQueueEntryPublicStateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsQueueCheckout", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "sessionToken" }, "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/public/tickets/queue/exit": { "post": { "summary": "Exit a mutable public ticket queue entry", "tags": [ "Public" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueSessionInput" } } } }, "responses": { "200": { "description": "Idempotent terminal browser-bound queue exit state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketQueueExitEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Operator role, tenant, Event secret, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, queue, entry, or browser-bound session was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Queue configuration, public selector, or session input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public queue or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsQueueExit", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "sessionToken" }, "x-vsm-ticket-queue-contract": "vsm-ticket-queue-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Operator role, tenant, Event secret, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, queue, entry, or browser-bound session was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Queue lifecycle, capacity, admission, exit, or offering sale state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Queue configuration, public selector, or session input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public queue or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, queue secret, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Persists tenant/Offering-scoped queue configuration, lifecycle, entries, and counters" }, { "kind": "audit", "description": "Appends immutable tenant-scoped Ticket queue events" } ] } } }, "/api/public/tickets/orders": { "post": { "summary": "Create public ticket order and Stripe Checkout Session", "tags": [ "Public" ], "responses": { "200": { "description": "Pending public Ticket order and Stripe Checkout handoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketOrderCreateEnvelope" } } } }, "400": { "description": "Request body or query cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, API key, or optional Embed session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, API scope, tenant, secret link, or Embed origin denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, offering, order, linked resource, or secret Event was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public or credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTicketsOrders", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTicketOrderCreateInput" } } } }, "x-vsm-ticket-purchase-contract": "vsm-ticket-purchase-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or query cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, API key, or optional Embed session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, API scope, tenant, secret link, or Embed origin denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, offering, order, linked resource, or secret Event was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, inventory, version, payment, seat, queue, or fulfillment conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Offering, order, URL, pagination, pricing, or tenant linkage is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public or credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, Redis, Stripe, or required runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Reserves inventory and persists the pending TicketOrder atomically" }, { "kind": "persistence", "description": "Links and renews the exact seat-hold group for the order", "conditional": true }, { "kind": "provider", "description": "Creates one idempotent Stripe Checkout Session and stores its safe identifiers" } ] } } }, "/api/v1/native-handoffs/{locationId}": { "get": { "summary": "List Location-bound QR and native handoff targets", "tags": [ "Venues" ], "responses": { "200": { "description": "Location-bound direct profile, booking, and exact Event targets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeHandoffProjectionEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/manager role or venues:read API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or public app URL configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-native-handoff-contract": "vsm-native-handoff-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/manager role or venues:read API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or public app URL configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "render", "description": "Resolves tenant-scoped public target readiness without persistence" } ] }, "operationId": "getApiV1NativeHandoffsByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "venues:read", "credentialName": "Authorization" } } }, "/api/v1/native-handoffs/{locationId}/qr": { "get": { "summary": "Generate one Location-bound PNG QR artifact", "tags": [ "Venues" ], "responses": { "200": { "description": "Private no-store PNG QR artifact", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/manager role or venues:read API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Selected profile, booking flow, or exact Event is not publicly available", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Action, Event, QR size, template, or locale is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or public app URL configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "action", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/NativeHandoffAction" } }, { "name": "eventId", "in": "query", "required": false, "description": "Required only for action=event; must belong to this Location", "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 256, 512, 1024 ], "default": 512 } } ], "x-vsm-native-handoff-contract": "vsm-native-handoff-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/manager role or venues:read API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Selected profile, booking flow, or exact Event is not publicly available" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Action, Event, QR size, template, or locale is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or public app URL configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "render", "description": "Generates one private no-store QR artifact in memory without persistence" } ] }, "operationId": "getApiV1NativeHandoffsByLocationIdQr", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "venues:read", "credentialName": "Authorization" } } }, "/api/v1/native-handoffs/{locationId}/pdf": { "get": { "summary": "Generate one printable Location-bound QR PDF", "tags": [ "Venues" ], "responses": { "200": { "description": "Private no-store printable QR PDF artifact", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/manager role or venues:read API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Selected profile, booking flow, or exact Event is not publicly available", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Action, Event, QR size, template, or locale is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or public app URL configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "action", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/NativeHandoffAction" } }, { "name": "eventId", "in": "query", "required": false, "description": "Required only for action=event; must belong to this Location", "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "template", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "poster", "tableTent", "sticker" ], "default": "poster" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ], "x-vsm-native-handoff-contract": "vsm-native-handoff-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/manager role or venues:read API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Selected profile, booking flow, or exact Event is not publicly available" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Action, Event, QR size, template, or locale is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or public app URL configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "render", "description": "Generates one private no-store QR artifact in memory without persistence" } ] }, "operationId": "getApiV1NativeHandoffsByLocationIdPdf", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "venues:read", "credentialName": "Authorization" } } }, "/api/v1/venue-profiles/{locationId}": { "get": { "summary": "Read the tenant-scoped venue profile editor state", "tags": [ "Venues" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Tenant-scoped Venue Profile editor projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileAdminEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or venues API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location or active published profile was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1VenueProfilesByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "venues:read", "credentialName": "Authorization" }, "x-vsm-venue-profile-contract": "vsm-venue-profile-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or venues API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location or active published profile was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "patch": { "summary": "Create or update the one editable venue profile draft", "tags": [ "Venues" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileDraftSaveInput" } } } }, "responses": { "200": { "description": "Updated immutable Venue Profile draft projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileAdminEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or venues API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location or active published profile was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Optimistic revision, timestamp, or lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Venue profile input is invalid or not publishable", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1VenueProfilesByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "venues:write", "credentialName": "Authorization" }, "x-vsm-venue-profile-contract": "vsm-venue-profile-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or venues API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location or active published profile was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Optimistic revision, timestamp, or lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Venue profile input is invalid or not publishable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped immutable Venue Profile version state" }, { "kind": "audit", "description": "Writes a PII-minimal Venue Profile lifecycle audit event" } ] } } }, "/api/v1/venue-profiles/{locationId}/publish": { "post": { "summary": "Atomically publish the exact venue profile draft revision", "tags": [ "Venues" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfilePublishInput" } } } }, "responses": { "200": { "description": "Atomically published Venue Profile projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileAdminEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or venues API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location or active published profile was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Optimistic revision, timestamp, or lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Venue profile input is invalid or not publishable", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1VenueProfilesByLocationIdPublish", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "venues:write", "credentialName": "Authorization" }, "x-vsm-venue-profile-contract": "vsm-venue-profile-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or venues API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location or active published profile was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Optimistic revision, timestamp, or lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Venue profile input is invalid or not publishable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped immutable Venue Profile version state" }, { "kind": "audit", "description": "Writes a PII-minimal Venue Profile lifecycle audit event" }, { "kind": "public-visibility", "description": "Changes the direct public Location profile snapshot" } ] } } }, "/api/v1/venue-profiles/{locationId}/archive": { "post": { "summary": "Remove a venue profile from public reads without deleting history", "tags": [ "Venues" ], "parameters": [ { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileArchiveInput" } } } }, "responses": { "200": { "description": "Archived Venue Profile projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueProfileAdminEnvelope" } } } }, "401": { "description": "Operator session or API key is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role or venues API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Location or active published profile was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Optimistic revision, timestamp, or lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Venue profile input is invalid or not publishable", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or API-key quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1VenueProfilesByLocationIdArchive", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "venues:write", "credentialName": "Authorization" }, "x-vsm-venue-profile-contract": "vsm-venue-profile-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or API key is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role or venues API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Location or active published profile was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Optimistic revision, timestamp, or lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Venue profile input is invalid or not publishable" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or API-key quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped immutable Venue Profile version state" }, { "kind": "audit", "description": "Writes a PII-minimal Venue Profile lifecycle audit event" }, { "kind": "public-visibility", "description": "Changes the direct public Location profile snapshot" } ] } } }, "/api/v1/website-sync": { "get": { "summary": "Read tenant Location Website-Sync state", "tags": [ "Website Sync" ], "parameters": [ { "name": "locationId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Complete Location-scoped Website-Sync state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncStateEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebsiteSync", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebsiteSyncStateQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/website-verifications": { "get": { "summary": "List Website-Sync domain verifications", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Location-scoped verification list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncVerificationListEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebsiteVerifications", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "locationId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebsiteSyncStateQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create one-time domain verification proof", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Pending verification and one-time placement proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncVerificationCreateEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Website-Sync encryption is not safely configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteVerifications", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncVerificationCreateInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Website-Sync encryption is not safely configured" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-verifications/{verificationId}/retry": { "post": { "summary": "Retry a pending or failed domain verification", "tags": [ "Website Sync" ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Requeued Website verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncVerificationEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteVerificationsByVerificationIdRetry", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-verifications/{verificationId}": { "delete": { "summary": "Revoke domain verification and dependent work", "tags": [ "Website Sync" ], "parameters": [ { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Revoked Website verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncVerificationEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1WebsiteVerificationsByVerificationId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-import-consents": { "post": { "summary": "Grant versioned Website-Sync import consent", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Versioned active Website-import consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncConsentEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportConsents", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncConsentCreateInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" } ] } } }, "/api/v1/website-import-consents/{consentId}": { "delete": { "summary": "Revoke Website-Sync import consent", "tags": [ "Website Sync" ], "parameters": [ { "name": "consentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Revoked Website-import consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncConsentEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "deleteApiV1WebsiteImportConsentsByConsentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-import-runs": { "get": { "summary": "List tenant Website-Sync import runs", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Cursor-paginated Website-import runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunPageEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebsiteImportRuns", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebsiteSyncRunListQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Queue a verified consented Website-Sync scan", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Queued or existing active Website-import run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportRuns", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunCreateInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-import-runs/{runId}": { "get": { "summary": "Read one tenant Website-Sync import run", "tags": [ "Website Sync" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Tenant-scoped Website-import run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebsiteImportRunsByRunId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/website-import-runs/{runId}/cancel": { "post": { "summary": "Cancel an active Website-Sync import run", "tags": [ "Website Sync" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Cancelled Website-import run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportRunsByRunIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true } ] } } }, "/api/v1/website-import-runs/{runId}/apply": { "post": { "summary": "Apply selected reviewed Website-Sync fields", "tags": [ "Website Sync" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Selected Website-import changes applied atomically", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportRunsByRunIdApply", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunApplyInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" } ] } } }, "/api/v1/website-import-runs/{runId}/undo": { "post": { "summary": "Undo one applied Website-Sync import without overwriting later changes", "tags": [ "Website Sync" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Website-import changes reverted without overwriting drift", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncRunEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportRunsByRunIdUndo", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" } ] } } }, "/api/v1/website-import-schedules": { "get": { "summary": "List Website-Sync schedules for a Location", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Location-scoped Website-import schedules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncScheduleListEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1WebsiteImportSchedules", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "locationId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-query-schema": { "$ref": "#/components/schemas/WebsiteSyncStateQuery" }, "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } }, "post": { "summary": "Create a recurring Website-Sync scan and mail reminder schedule", "tags": [ "Website Sync" ], "responses": { "200": { "description": "Active recurring Website-import schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncScheduleEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1WebsiteImportSchedules", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncScheduleCreateInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "audit", "description": "Writes a PII-minimal immutable audit event" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true }, { "kind": "mail", "description": "Queues an Owner/Manager schedule reminder when due", "conditional": true } ] } } }, "/api/v1/website-import-schedules/{scheduleId}": { "patch": { "summary": "Update, pause, or resume a Website-Sync schedule", "tags": [ "Website Sync" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Updated Website-import schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncScheduleEnvelope" } } } }, "401": { "description": "Interactive operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is required", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner or Manager membership, active verification, or active consent is required", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Website-Sync resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Website-Sync state transition or undo conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body or query is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "patchApiV1WebsiteImportSchedulesByScheduleId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteSyncScheduleUpdateInput" } } } }, "x-vsm-website-sync-contract": "vsm-website-sync-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Interactive operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is required" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner or Manager membership, active verification, or active consent is required" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Website-Sync resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Website-Sync state transition or undo conflicts" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body or query is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Website-Sync lifecycle state" }, { "kind": "worker", "description": "Makes bounded Website-Sync Worker processing eligible", "conditional": true }, { "kind": "mail", "description": "Queues an Owner/Manager schedule reminder when due", "conditional": true } ] } } }, "/api/v1/launch-center": { "get": { "summary": "Read the tenant-scoped guided launch readiness model", "tags": [ "Operations" ], "responses": { "200": { "description": "Private tenant launch-readiness aggregate with entitlement-aware steps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenterEnvelope" } } } }, "401": { "description": "Authenticated operator or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant membership or tickets:read scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal read-model failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1LaunchCenter", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-workspace-aggregates-contract": "vsm-workspace-aggregates-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [ "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant membership or tickets:read scope denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal read-model failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/operator-inbox": { "get": { "summary": "Read the tenant-scoped operator work queue", "tags": [ "Operations" ], "responses": { "200": { "description": "Private bounded operator work queue derived from tenant workflows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAggregateOperatorInboxEnvelope" } } } }, "401": { "description": "Authenticated operator or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant membership or tickets:read scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal read-model failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1OperatorInbox", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" }, "x-vsm-workspace-aggregates-contract": "vsm-workspace-aggregates-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [ "calendar.booking", "ticketing.checkout" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant membership or tickets:read scope denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal read-model failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/v1/ticket-workspace": { "get": { "summary": "Read the tenant-scoped ticket operations workspace", "tags": [ "Ticketing" ], "responses": { "200": { "description": "Private PII-minimized ticket operations aggregate without access secrets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAggregateTicketWorkspaceEnvelope" } } } }, "401": { "description": "Authenticated operator or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant membership or tickets:read scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Requested ticket offering does not exist for this tenant", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Optional offering filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal read-model failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketWorkspace", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-workspace-aggregates-contract": "vsm-workspace-aggregates-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator or API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant membership or tickets:read scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Requested ticket offering does not exist for this tenant" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Optional offering filter is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal read-model failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "parameters": [ { "name": "offeringId", "in": "query", "required": false, "description": "Scopes the bounded Event-Day entry queue to one tenant offering; aggregate metrics remain tenant-wide.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ] } }, "/api/v1/tickets/{ticketId}": { "get": { "summary": "Read one tenant-scoped ticket", "tags": [ "Ticketing" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "One tenant-scoped Ticket for authorized staff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "401": { "description": "Operator session or tenant API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ticketing.checkout is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Staff role, API scope, tenant, or access code denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, Ticket, offering, offline device, or offline package was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Operator or API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or required check-in runtime configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1TicketsByTicketId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "tickets:read", "credentialName": "Authorization" }, "x-vsm-ticket-check-in-contract": "vsm-ticket-check-in-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "ticketing.checkout", "features": [ "ticketing.checkout" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator session or tenant API credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ticketing.checkout is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Staff role, API scope, tenant, or access code denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, Ticket, offering, offline device, or offline package was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Scan code, timestamp, UUID, digest, package expiry, queue, or filter is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Operator or API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or required check-in runtime configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/self-service/bookings/{bookingId}": { "get": { "summary": "Read a booking through its signed customer self-service token", "tags": [ "Public", "Bookings" ], "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "X-VSM-Booking-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 24, "maxLength": 4096 }, "description": "Signed booking self-service token from the customer link." } ], "responses": { "200": { "description": "Sanitized signed booking self-service state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSelfServiceStateEnvelope" } } } }, "401": { "description": "Signed token is invalid, expired, or does not match the booking", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive for the booking tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Booking, tenant, location, or calendar was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Token shape or replacement booking window is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public booking self-service rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Signed-token or required persistence configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiPublicSelfServiceBookingsByBookingId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "header", "csrfRequiredForCookieSession": false, "credentialName": "X-VSM-Booking-Token" }, "x-vsm-booking-self-service-contract": "vsm-booking-self-service-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Signed token is invalid, expired, or does not match the booking" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive for the booking tenant" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Booking, tenant, location, or calendar was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Token shape or replacement booking window is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public booking self-service rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Signed-token or required persistence configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] } } }, "/api/public/self-service/bookings/{bookingId}/cancel": { "post": { "summary": "Cancel a booking through its signed customer self-service token", "tags": [ "Public", "Bookings" ], "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Cancelled booking, mail summary, and support case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSelfServiceCancelEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Signed token is invalid, expired, or does not match the booking", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive for the booking tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Booking, tenant, location, or calendar was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Token shape or replacement booking window is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public booking self-service rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Signed-token or required persistence configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicSelfServiceBookingsByBookingIdCancel", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSelfServiceCancelInput" } } } }, "x-vsm-booking-self-service-contract": "vsm-booking-self-service-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Signed token is invalid, expired, or does not match the booking" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive for the booking tenant" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Booking, tenant, location, or calendar was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Token shape or replacement booking window is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public booking self-service rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Signed-token or required persistence configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-self-service-cancel", "description": "Transitions the eligible booking to cancelled." }, { "kind": "booking-customer-mail", "description": "Queues the tenant cancellation mail when an address exists.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues matching booking.cancelled webhook deliveries.", "conditional": true }, { "kind": "support-case-create", "description": "Creates a tenant-scoped bookingSelfService support case." } ] } } }, "/api/public/self-service/bookings/{bookingId}/reschedule": { "post": { "summary": "Reschedule a booking through its signed customer self-service token", "tags": [ "Public", "Bookings" ], "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Rescheduled booking, capacity decision, mail summary, and support case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSelfServiceRescheduleEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Signed token is invalid, expired, or does not match the booking", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive for the booking tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Booking, tenant, location, or calendar was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Token shape or replacement booking window is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public booking self-service rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Signed-token or required persistence configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicSelfServiceBookingsByBookingIdReschedule", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "request-body", "csrfRequiredForCookieSession": false, "credentialName": "token" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingSelfServiceRescheduleInput" } } } }, "x-vsm-booking-self-service-contract": "vsm-booking-self-service-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Signed token is invalid, expired, or does not match the booking" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive for the booking tenant" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Booking, tenant, location, or calendar was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Booking state, cutoff, check-in, availability, or capacity prevents the action" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Token shape or replacement booking window is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public booking self-service rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Signed-token or required persistence configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-capacity-lock", "description": "Validates the new window and capacity under the distributed booking lock." }, { "kind": "booking-self-service-reschedule", "description": "Persists the eligible booking's replacement window and slot." }, { "kind": "booking-customer-mail", "description": "Queues a fresh confirmation mail with replacement ICS metadata.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues matching booking.rescheduled webhook deliveries.", "conditional": true }, { "kind": "support-case-create", "description": "Creates a tenant-scoped bookingSelfService support case." } ] } } }, "/api/v1/memberships/products": { "get": { "summary": "List Membership Products", "tags": [ "Memberships" ], "responses": { "200": { "description": "Membership Product catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductListEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1MembershipsProducts", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" } }, "post": { "summary": "Create Membership Product", "tags": [ "Memberships" ], "responses": { "201": { "description": "Created Membership Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductCreateInput" } } } }, "parameters": [], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsProducts", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/products/{productId}": { "get": { "summary": "Get Membership Product", "tags": [ "Memberships" ], "responses": { "200": { "description": "Membership Product detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1MembershipsProductsByProductId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" } }, "patch": { "summary": "Update Membership Product", "tags": [ "Memberships" ], "responses": { "200": { "description": "Updated Membership Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductUpdateInput" } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[0-9]+\"$" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "patchApiV1MembershipsProductsByProductId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/products/{productId}/activate": { "post": { "summary": "Activate Membership Product", "tags": [ "Memberships" ], "responses": { "200": { "description": "Activated Membership Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsProductsByProductIdActivate", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/products/{productId}/archive": { "post": { "summary": "Archive Membership Product", "tags": [ "Memberships" ], "responses": { "200": { "description": "Archived Membership Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipProductEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsProductsByProductIdArchive", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships": { "get": { "summary": "List Customer Memberships", "tags": [ "Memberships" ], "responses": { "200": { "description": "Tenant Membership assignments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipListEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "name": "includeInactive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1Memberships", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" } }, "post": { "summary": "Assign Customer Membership", "tags": [ "Memberships" ], "responses": { "201": { "description": "Assigned Customer Membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipCreateInput" } } } }, "parameters": [], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "membership-ledger", "description": "Appends an idempotent immutable quota ledger entry" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1Memberships", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}": { "get": { "summary": "Get Customer Membership", "tags": [ "Memberships" ], "responses": { "200": { "description": "Customer Membership detail and bounded ledger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1MembershipsByMembershipId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "loyalty:read", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}/pause": { "post": { "summary": "Pause Customer Membership", "tags": [ "Memberships" ], "responses": { "200": { "description": "Paused Customer Membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsByMembershipIdPause", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}/resume": { "post": { "summary": "Resume Customer Membership", "tags": [ "Memberships" ], "responses": { "200": { "description": "Resumed Customer Membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsByMembershipIdResume", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}/cancel": { "post": { "summary": "Cancel Customer Membership", "tags": [ "Memberships" ], "responses": { "200": { "description": "Cancelled Customer Membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsByMembershipIdCancel", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}/adjust": { "post": { "summary": "Adjust Customer Membership quota", "tags": [ "Memberships" ], "responses": { "200": { "description": "Adjusted Membership quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipAdjustmentInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[0-9]+\"$" } }, { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "membership-ledger", "description": "Appends an idempotent immutable quota ledger entry" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsByMembershipIdAdjust", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/memberships/{membershipId}/renew": { "post": { "summary": "Renew Customer Membership", "tags": [ "Memberships" ], "responses": { "200": { "description": "Renewed Membership quota and validity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[0-9]+\"$" } }, { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "membership-ledger", "description": "Appends an idempotent immutable quota ledger entry" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "postApiV1MembershipsByMembershipIdRenew", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "loyalty:write", "credentialName": "Authorization" } } }, "/api/v1/bookings/{bookingId}/membership": { "post": { "summary": "Apply Membership to Booking", "tags": [ "Memberships" ], "responses": { "200": { "description": "Applied Membership quota to Booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingMembershipApplyEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingMembershipApplyInput" } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "membership-ledger", "description": "Appends an idempotent immutable quota ledger entry" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" }, { "kind": "booking-cancellation-release", "description": "Booking cancellation restores linked finite quota atomically", "conditional": true } ] }, "operationId": "postApiV1BookingsByBookingIdMembership", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" } }, "delete": { "summary": "Release Membership from Booking", "tags": [ "Memberships" ], "responses": { "200": { "description": "Released Membership quota from Booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingMembershipReleaseEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "membership-ledger", "description": "Appends an idempotent immutable quota ledger entry" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" } ] }, "operationId": "deleteApiV1BookingsByBookingIdMembership", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" } } }, "/api/v1/customer-account/{tenantSlug}/memberships": { "get": { "summary": "List verified Customer Memberships", "tags": [ "Memberships" ], "responses": { "200": { "description": "Private verified-Customer Membership wallet, offers, subscriptions, and invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMembershipBillingOverviewEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CustomerAccountByTenantSlugMemberships", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/customer-account/{tenantSlug}/memberships/{productId}/checkout": { "post": { "summary": "Create recurring Membership Checkout", "tags": [ "Memberships", "Billing" ], "responses": { "201": { "description": "Hosted recurring Membership Checkout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipCheckoutEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Product, Membership, Booking, or ledger state" }, { "kind": "audit", "description": "Writes a tenant-scoped PII-minimal operator audit event" }, { "kind": "stripe-checkout", "description": "Creates a hosted recurring Stripe Checkout; entitlement starts only after a signed paid-invoice webhook" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugMembershipsByProductIdCheckout" } }, "/api/v1/customer-account/{tenantSlug}/memberships/{subscriptionId}/portal": { "post": { "summary": "Create Membership Billing Portal", "tags": [ "Memberships", "Billing" ], "responses": { "200": { "description": "Hosted Membership billing management", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipBillingPortalEnvelope" } } } }, "401": { "description": "Operator/API credential or verified Customer session is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "loyalty.programs is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant role, ownership, or loyalty API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, version, service, Booking, or quota state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Membership input or required header is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API-key or Customer-account rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-membership-contract": "vsm-customer-membership-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "loyalty.programs", "features": [ "loyalty.programs" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator/API credential or verified Customer session is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "loyalty.programs is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant role, ownership, or loyalty API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Product, Customer, Membership, or Booking was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, version, service, Booking, or quota state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Membership input or required header is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API-key or Customer-account rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL persistence is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "stripe-billing-portal", "description": "Creates a short-lived Stripe Billing Portal session" } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugMembershipsBySubscriptionIdPortal" } }, "/api/v1/admin/documents": { "get": { "summary": "List platform documents", "responses": { "200": { "description": "Platform document inventory with draft, history, and receipt aggregates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminDocuments", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Create platform document", "responses": { "200": { "description": "Created platform document with initial draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the bounded JSON limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentCreateInput" } } } }, "parameters": [], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the bounded JSON limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates a document and immutable version lineage" }, { "kind": "audit", "description": "Writes platform_document.created atomically" } ] }, "operationId": "postApiV1AdminDocuments", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/documents/{documentId}/revisions": { "post": { "summary": "Create platform document revision", "responses": { "200": { "description": "Created the next editable document version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the bounded JSON limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentRevisionCreateInput" } } } }, "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the bounded JSON limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Creates one new draft version" }, { "kind": "audit", "description": "Writes platform_document.revision_created atomically" } ] }, "operationId": "postApiV1AdminDocumentsByDocumentIdRevisions", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/documents/{documentId}/draft": { "put": { "summary": "Save platform document draft", "responses": { "200": { "description": "CAS-updated document draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the bounded JSON limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentDraftSaveInput" } } } }, "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the bounded JSON limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Updates only the mutable draft using expectedRevision" }, { "kind": "audit", "description": "Writes platform_document.draft_saved atomically" } ] }, "operationId": "putApiV1AdminDocumentsByDocumentIdDraft", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/documents/{documentId}/publish": { "post": { "summary": "Publish platform document", "responses": { "200": { "description": "Published document revision and durable recipient fan-out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the bounded JSON limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentPublishInput" } } } }, "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the bounded JSON limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Supersedes the prior revision and locks published content" }, { "kind": "notification", "description": "Creates durable receipts and transactional email jobs" }, { "kind": "audit", "description": "Writes platform_document.published atomically" } ] }, "operationId": "postApiV1AdminDocumentsByDocumentIdPublish", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/documents/{documentId}/archive": { "post": { "summary": "Archive platform document", "responses": { "200": { "description": "Archived platform document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentAdminEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the bounded JSON limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentArchiveInput" } } } }, "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the bounded JSON limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Archives the document without deleting revision evidence" }, { "kind": "audit", "description": "Writes platform_document.archived atomically" } ] }, "operationId": "postApiV1AdminDocumentsByDocumentIdArchive", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/platform-documents": { "get": { "summary": "List operator platform documents", "responses": { "200": { "description": "User- and tenant-scoped effective platform documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentOperatorEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1PlatformDocuments", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/platform-documents/{revisionId}/open": { "post": { "summary": "Open operator platform document", "responses": { "200": { "description": "Idempotently opened a platform document receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentOperatorEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Stores the first openedAt timestamp", "conditional": true }, { "kind": "audit", "description": "Writes platform_document.opened on first open", "conditional": true } ] }, "operationId": "postApiV1PlatformDocumentsByRevisionIdOpen", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/platform-documents/{revisionId}/acknowledge": { "post": { "summary": "Acknowledge operator platform document", "responses": { "200": { "description": "Idempotently acknowledged the exact opened content hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDocumentOperatorEnvelope" } } } }, "401": { "description": "Authenticated session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform capability, tenant role, or user-bound session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Document, revision, target tenant, or receipt was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Document content, audience, locale, key, or lifecycle input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized platform-document failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL persistence or public application URL is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "revisionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ], "x-vsm-platform-documents-contract": "vsm-platform-documents-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform capability, tenant role, or user-bound session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Document, revision, target tenant, or receipt was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Revision changed, draft state conflicts, or acknowledgement was attempted before opening" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Document content, audience, locale, key, or lifecycle input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized platform-document failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL persistence or public application URL is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Stores acknowledgement timestamp and immutable content hash", "conditional": true }, { "kind": "audit", "description": "Writes platform_document.acknowledged once", "conditional": true } ] }, "operationId": "postApiV1PlatformDocumentsByRevisionIdAcknowledge", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing": { "get": { "summary": "Read the tenant Social Publishing workspace", "tags": [ "Social Publishing" ], "parameters": [], "responses": { "200": { "description": "Sanitized Social Publishing workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingWorkspaceEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1SocialPublishing", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/meta/start": { "post": { "summary": "Start a Meta OAuth connection", "tags": [ "Social Publishing" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingMetaStartInput" } } } }, "responses": { "200": { "description": "Short-lived Meta authorization handoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingAuthorizationEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Stores a one-use hashed OAuth state and encrypted PKCE verifier" } ] }, "operationId": "postApiV1SocialPublishingMetaStart", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/meta/callback": { "get": { "summary": "Complete the Meta OAuth connection", "tags": [ "Social Publishing" ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 4000 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } } ], "responses": { "303": { "description": "Redirect to the Social Publishing workspace", "headers": { "Location": { "description": "Same-origin dashboard outcome redirect", "schema": { "type": "string", "format": "uri-reference" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Consumes the OAuth state and exchanges the provider code" }, { "kind": "database-write", "description": "Stores encrypted tenant-scoped Meta Page credentials" } ] }, "operationId": "getApiV1SocialPublishingMetaCallback", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/connections/{connectionId}/revoke": { "post": { "summary": "Revoke a Meta publishing connection", "tags": [ "Social Publishing" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Sanitized revoked connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingConnectionEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Best-effort Meta permission revocation", "conditional": true }, { "kind": "database-write", "description": "Revokes the local connection and cancels scheduled jobs" } ] }, "operationId": "postApiV1SocialPublishingConnectionsByConnectionIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/jobs": { "post": { "summary": "Schedule a Social Publishing job", "tags": [ "Social Publishing" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingJobCreateInput" } } } }, "responses": { "200": { "description": "Durable scheduled publishing job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingJobScheduledEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Creates a tenant-scoped durable publishing job" }, { "kind": "async-job", "description": "A recurring Worker publishes the requested channels" } ] }, "operationId": "postApiV1SocialPublishingJobs", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/jobs/{jobId}/retry": { "post": { "summary": "Retry a failed Social Publishing job", "tags": [ "Social Publishing" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Failed publishing job requeued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingRetryEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Requeues a terminal failed tenant-owned job" } ] }, "operationId": "postApiV1SocialPublishingJobsByJobIdRetry", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/social-publishing/jobs/{jobId}/cancel": { "post": { "summary": "Cancel a scheduled Social Publishing job", "tags": [ "Social Publishing" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Scheduled publishing job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPublishingCancelEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Cancels a still-scheduled tenant-owned job" } ] }, "operationId": "postApiV1SocialPublishingJobsByJobIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business": { "get": { "summary": "Read the Google Business Profile workspace", "tags": [ "Google Business" ], "parameters": [], "responses": { "200": { "description": "Sanitized Google Business Profile workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessWorkspaceEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1GoogleBusiness", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/start": { "post": { "summary": "Start a Google Business OAuth connection", "tags": [ "Google Business" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessStartInput" } } } }, "responses": { "200": { "description": "Short-lived Google authorization handoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessAuthorizationEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Stores a one-use hashed OAuth state and encrypted PKCE verifier" } ] }, "operationId": "postApiV1GoogleBusinessStart", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/callback": { "get": { "summary": "Complete the Google Business OAuth connection", "tags": [ "Google Business" ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 4000 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } } ], "responses": { "303": { "description": "Redirect to the Google Business workspace", "headers": { "Location": { "description": "Same-origin dashboard outcome redirect", "schema": { "type": "string", "format": "uri-reference" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Consumes OAuth state, exchanges PKCE code and discovers accounts" }, { "kind": "database-write", "description": "Stores encrypted provider tokens in a pending connection" } ] }, "operationId": "getApiV1GoogleBusinessCallback", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/connections/{connectionId}/locations": { "get": { "summary": "List managed Google Business locations", "tags": [ "Google Business" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Sanitized managed provider locations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessAvailableLocationsEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "May rotate an expired encrypted access token", "conditional": true } ] }, "operationId": "getApiV1GoogleBusinessConnectionsByConnectionIdLocations", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/connections/{connectionId}/select": { "post": { "summary": "Bind a managed Google listing", "tags": [ "Google Business" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessSelectInput" } } } }, "responses": { "200": { "description": "Activated sanitized Google Business connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessConnectionEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Revalidates the selected managed listing" }, { "kind": "database-write", "description": "Binds the listing to one tenant Location" } ] }, "operationId": "postApiV1GoogleBusinessConnectionsByConnectionIdSelect", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/connections/{connectionId}/refresh": { "post": { "summary": "Refresh a Google Business profile projection", "tags": [ "Google Business" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Refreshed sanitized Google Business connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessConnectionEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Reads the current managed listing profile" }, { "kind": "database-write", "description": "Stores the bounded remote profile projection" } ] }, "operationId": "postApiV1GoogleBusinessConnectionsByConnectionIdRefresh", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/connections/{connectionId}/sync": { "post": { "summary": "Queue selected Google Business profile fields", "tags": [ "Google Business" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessSyncInput" } } } }, "responses": { "200": { "description": "Durable Google Business sync run queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessSyncQueuedEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request input, OAuth state, URL, schedule, or field selection is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request input, OAuth state, URL, schedule, or field selection is invalid" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Snapshots selected local fields in a durable sync run" }, { "kind": "async-job", "description": "A recurring Worker applies the selected Google update mask" } ] }, "operationId": "postApiV1GoogleBusinessConnectionsByConnectionIdSync", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/connections/{connectionId}/revoke": { "post": { "summary": "Revoke a Google Business connection", "tags": [ "Google Business" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Sanitized revoked Google Business connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessConnectionEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Provider credentials, encryption key, or live provider access is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Provider credentials, encryption key, or live provider access is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-provider", "description": "Best-effort Google token revocation", "conditional": true }, { "kind": "database-write", "description": "Wipes local tokens and cancels active sync runs" } ] }, "operationId": "postApiV1GoogleBusinessConnectionsByConnectionIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/google-business/runs/{runId}/retry": { "post": { "summary": "Retry a failed Google Business sync run", "tags": [ "Google Business" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Failed Google Business sync run requeued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleBusinessRetryEnvelope" } } } }, "401": { "description": "Personal operator session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "tenant.core entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Owner/Manager role or personal-session requirement failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant context or tenant-scoped resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Resource state does not permit the requested command", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-social-profile-contract": "vsm-social-profile-openapi-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Personal operator session is missing or invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "tenant.core entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Owner/Manager role or personal-session requirement failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant context or tenant-scoped resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Resource state does not permit the requested command" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Requeues a terminal failed tenant-owned sync run" } ] }, "operationId": "postApiV1GoogleBusinessRunsByRunIdRetry", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/bookings/{bookingId}/reminder-plan": { "get": { "summary": "Read the automatic booking reminder plan", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReminderPlanEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1BookingsByBookingIdReminderPlan", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" } } }, "/api/v1/booking-services/reminder-preview": { "post": { "tags": [ "Bookings" ], "summary": "Preview booking reminder draft", "responses": { "200": { "description": "Read-only reminder draft with explicitly synthetic data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReminderPreviewEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingReminderPreviewInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "postApiV1BookingServicesReminderPreview", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/bookings/{bookingId}/correct-no-show": { "post": { "summary": "Correct a no-show to completed attendance", "tags": [ "Bookings" ], "responses": { "200": { "description": "Booking status workflow result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingWorkflowEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-no-show-correction", "description": "Corrects a no-show to completed attendance, atomically auditing the applied transition without reactivating reservations." }, { "kind": "booking-customer-mail", "description": "Queues the applicable transactional customer mail.", "conditional": true }, { "kind": "booking-webhook-outbox", "description": "Queues subscribed Booking webhook deliveries.", "conditional": true }, { "kind": "booking-loyalty-accrual", "description": "Accrues enabled loyalty points immediately or leaves a repairable pending marker.", "conditional": true } ] }, "operationId": "postApiV1BookingsByBookingIdCorrectNoShow" } }, "/api/v1/bookings/{bookingId}/recovery-plan": { "get": { "summary": "Read captured no-show recovery plan", "tags": [ "Bookings" ], "responses": { "200": { "description": "Tenant-scoped scheduling read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryPlanEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1BookingsByBookingIdRecoveryPlan", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "bookings:read", "credentialName": "Authorization" } } }, "/api/public/recovery/{tenantSlug}/{planId}": { "get": { "tags": [ "Public" ], "summary": "Purpose-bound booking recovery", "responses": { "200": { "description": "Current purpose-bound invitation or linked request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingRecoveryEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "X-VSM-Booking-Recovery-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 24, "maxLength": 2048, "x-vsm-sensitive": true } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true } ] }, "operationId": "getApiPublicRecoveryByTenantSlugByPlanId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "header", "csrfRequiredForCookieSession": false, "credentialName": "X-VSM-Booking-Recovery-Token" } } }, "/api/public/recovery/{tenantSlug}/{planId}/availability": { "get": { "tags": [ "Public" ], "summary": "Purpose-bound booking recovery", "responses": { "200": { "description": "Current slots for the original offer duration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCalendarAvailabilityEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "partySize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "name": "X-VSM-Booking-Recovery-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 24, "maxLength": 2048, "x-vsm-sensitive": true } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true } ] }, "operationId": "getApiPublicRecoveryByTenantSlugByPlanIdAvailability", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "header", "csrfRequiredForCookieSession": false, "credentialName": "X-VSM-Booking-Recovery-Token" } } }, "/api/public/recovery/{tenantSlug}/{planId}/bookings": { "post": { "tags": [ "Public" ], "summary": "Purpose-bound booking recovery", "responses": { "200": { "description": "One pending request with immutable original/new attribution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCreateEnvelope" } } } }, "401": { "description": "Optional Embed session or management credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking is inactive for the tenant", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Origin, tenant, Location, or Embed session denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the public JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Public Booking, Waitlist, date, or Calendar input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Public read or mutation rate limit is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required persistence, Redis, Worker, or mail configuration is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingRecoveryCreateInput" } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "X-VSM-Booking-Recovery-Token", "in": "header", "required": true, "schema": { "type": "string", "minLength": 24, "maxLength": 2048, "x-vsm-sensitive": true } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-vsm-public-booking-contract": "vsm-public-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Optional Embed session or management credential is invalid" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking is inactive for the tenant" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Origin, tenant, Location, or Embed session denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Public tenant, Location, Calendar, slot, or Waitlist entry was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, duplicate identity, token rotation, or lifecycle conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the public JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Public Booking, Waitlist, date, or Calendar input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Public read or mutation rate limit is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required persistence, Redis, Worker, or mail configuration is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes tenant-scoped Booking or Waitlist state" }, { "kind": "audit", "description": "Writes a PII-minimal public lifecycle audit event" }, { "kind": "mail-outbox", "description": "Transactional received mail only; no marketing invitation" }, { "kind": "webhook-outbox", "description": "Existing booking.created outbox" }, { "kind": "rate-limit", "description": "Consumes one bounded public rate-limit entry", "conditional": true } ] }, "operationId": "postApiPublicRecoveryByTenantSlugByPlanIdBookings", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "signedToken", "allowedPrincipals": [ "signed-token" ], "credentialLocation": "header", "csrfRequiredForCookieSession": false, "credentialName": "X-VSM-Booking-Recovery-Token" } } }, "/api/v1/admin/workflow-deliveries": { "get": { "summary": "Inspect persistent workflow execution receipts for one tenant", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AdminWorkflowDeliveryStatus" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "x-vsm-query-schema": { "$ref": "#/components/schemas/AdminWorkflowDeliveryQuery" }, "responses": { "200": { "description": "Tenant-bound persistent execution receipts without payloads or lease tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkflowDeliveryPageEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.worker.read", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminWorkflowDeliveries", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/workflow-deliveries/{deliveryId}/retry": { "post": { "summary": "Recover one eligible database-only execution with atomic audit", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkflowDeliveryRetryInput" } } } }, "responses": { "200": { "description": "CAS-guarded, atomically audited retry of a known database-only consumer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminWorkflowDeliveryRetryEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required Worker capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Queue, schedule, or failed job was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Job state or bounded schedule-command lock conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the JSON payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Pagination, identifier, reason, or idempotency input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.worker.write", "x-vsm-worker-operations-contract": "vsm-worker-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required Worker capability is missing" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Queue, schedule, or failed job was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Job state or bounded schedule-command lock conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the JSON payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Pagination, identifier, reason, or idempotency input is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "database-write", "description": "Resets one eligible receipt and records its audit in the same PostgreSQL transaction; no synchronous provider call or booking mutation" } ] }, "operationId": "postApiV1AdminWorkflowDeliveriesByDeliveryIdRetry", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/communication-policy": { "get": { "summary": "GET tenant communication policy", "tags": [ "Communication" ], "responses": { "200": { "description": "Current tenant communication policy; absent storage is disabled revision zero", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationPolicyEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CommunicationPolicy", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "communication:read", "credentialName": "Authorization" } }, "patch": { "summary": "PATCH tenant communication policy", "tags": [ "Communication" ], "responses": { "200": { "description": "Versioned tenant communication policy updated atomically", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationPolicyEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationPolicyInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "audit", "description": "Atomically appends a tenant-bound revision audit without contact data" } ] }, "operationId": "patchApiV1CommunicationPolicy", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "communication:write", "credentialName": "Authorization" } } }, "/api/v1/communication-usage": { "get": { "operationId": "getApiV1CommunicationUsage", "responses": { "200": { "description": "Current UTC nontransactional transport usage and safe recent reservations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsageEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "usage:read", "credentialName": "Authorization" } } }, "/api/v1/communication-usage/budget": { "patch": { "operationId": "patchApiV1CommunicationUsageBudget", "responses": { "200": { "description": "Owner budget update with atomic audit and queued-message wake", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsageEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationBudgetInput" } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "audit", "description": "Atomically records owner budget revision without recipient data" } ] }, "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/communication-usage/reservations/{reservationId}": { "get": { "parameters": [ { "name": "reservationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Scoped receipt inspection with bounded verified-relay evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsageDetailEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CommunicationUsageReservationsByReservationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "usage:read", "credentialName": "Authorization" } } }, "/api/v1/communication-usage/reservations/{reservationId}/reconcile": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsageReconcileInput" } } } }, "parameters": [ { "name": "reservationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Fenced idempotent Owner reconciliation without provider I/O or resending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsageReconcileEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "audit", "description": "Atomically records selected verified evidence, operator reason and resulting revision" } ] }, "operationId": "postApiV1CommunicationUsageReservationsByReservationIdReconcile", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/communication-usage/family-transport-holds": { "get": { "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Bounded keyset page of held family booking mail claims with signed-relay evidence summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyTransportHoldEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "security": [ { "operatorSession": [] } ], "operationId": "getApiV1CommunicationUsageFamilyTransportHolds", "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/communication-usage/family-transport-holds/{messageId}/resolve": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyTransportResolveInput" } } } }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Fenced idempotent Owner settlement of one held family mail claim without provider I/O or resending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyTransportResolveEnvelope" } } } }, "400": { "description": "Request body cannot be parsed as JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Lifecycle, capacity, revision, or idempotency state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the route payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body cannot be parsed as JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Lifecycle, capacity, revision, or idempotency state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the route payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Writes the tenant-scoped Communication state in PostgreSQL" }, { "kind": "audit", "description": "Atomically records the selected relay evidence or assumed-delivered closure, operator reason and the released claim" } ] }, "security": [ { "operatorSession": [], "csrfToken": [] } ], "operationId": "postApiV1CommunicationUsageFamilyTransportHoldsByMessageIdResolve", "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/communication-usage/reservations": { "get": { "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "afterId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Bounded keyset page of unresolved UNKNOWN usage, including prior periods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunicationUsagePendingEnvelope" } } } }, "401": { "description": "Operator, Customer, or callback authentication is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, CSRF, tenant, or verified Customer ownership denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped Communication resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Identifier, filter, content, recipient, or schedule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-communication-mail-contract": "vsm-communication-mail-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Customer, or callback authentication is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, CSRF, tenant, or verified Customer ownership denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped Communication resource was not found" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Identifier, filter, content, recipient, or schedule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required PostgreSQL, Redis, worker, mail, or callback secret is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CommunicationUsageReservations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "usage:read", "credentialName": "Authorization" } } }, "/api/v1/bookings/{bookingId}/stop-recovery": { "post": { "tags": [ "Bookings" ], "summary": "Stop the active no-show follow-up", "responses": { "200": { "description": "Stopped tenant recovery plan and current delivery state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryPlanEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-recovery-stop", "description": "Atomically stops active follow-up, cancels queued linked mail and records one minimal audit. Replays do not send or repeat the audit; in-flight provider acceptance cannot be recalled." } ] }, "operationId": "postApiV1BookingsByBookingIdStopRecovery", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" } } }, "/api/v1/booking-services/recovery-preview": { "post": { "tags": [ "Bookings" ], "summary": "Preview a recovery invitation draft with synthetic data", "responses": { "200": { "description": "Read-only recovery draft with synthetic data and non-actionable links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryPreviewEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryPreviewInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "postApiV1BookingServicesRecoveryPreview", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/bookings/{bookingId}/retry-recovery": { "post": { "tags": [ "Bookings" ], "summary": "Retry a confirmed non-accepted recovery invitation", "parameters": [ { "name": "bookingId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Durable retry intent and current plan state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryRetryEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Authenticated operator session or API credential required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "calendar.booking entitlement is inactive", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Role, scope, tenant, or CSRF check failed", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant-scoped scheduling resource was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Capacity, availability, lifecycle, or identity conflict", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request body, query, relation, or scheduling rule is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "API credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRecoveryRetryInput" } } } }, "x-vsm-booking-contract": "vsm-booking-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session or API credential required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "calendar.booking entitlement is inactive" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Role, scope, tenant, or CSRF check failed" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant-scoped scheduling resource was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Capacity, availability, lifecycle, or identity conflict" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Request body, query, relation, or scheduling rule is invalid" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "API credential request quota is exhausted" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "booking-recovery-retry", "description": "Persists the tenant-scoped scheduling mutation." } ] }, "operationId": "postApiV1BookingsByBookingIdRetryRecovery", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "bookings:write", "credentialName": "Authorization" } } }, "/api/v1/leads": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "in": "query", "name": "stage", "required": false, "schema": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1Leads", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } }, "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCaptureInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1Leads", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/options", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "includeInactive", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionDetailEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/move": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/move", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMoveInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdMove", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/close": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/close", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCloseInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdClose", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/reopen": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/reopen", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionReopenInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdReopen", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/prospect-contacts/{contactId}/export": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/prospect-contacts/{contactId}/export", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionExportEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ProspectContactsByContactIdExport", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/prospect-contacts/{contactId}/erase": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/prospect-contacts/{contactId}/erase", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionErasureInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionErasureEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1ProspectContactsByContactIdErase", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/public/acquisition/{tenantSlug}/{serviceId}": { "get": { "summary": "Tenant-bound acquisition GET /api/public/acquisition/{tenantSlug}/{serviceId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ] } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterestFormEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiPublicAcquisitionByTenantSlugByServiceId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/acquisition/{tenantSlug}/{serviceId}/requests": { "post": { "summary": "Tenant-bound acquisition POST /api/public/acquisition/{tenantSlug}/{serviceId}/requests", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-interest-token", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterestInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInterestReceiptEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Offer-bound anonymous inquiry; atomic unverified contact, interest, separate inquiry/marketing request, minimal event and receipt. No existing contact overwrite, account, booking, mail or marketing enrollment." } ] }, "operationId": "postApiPublicAcquisitionByTenantSlugByServiceIdRequests", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/v1/leads/{leadId}/booking-options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/booking-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionBookingOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdBookingOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/link-booking": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/link-booking", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionLinkBookingInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdLinkBooking", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/unlink-booking": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/unlink-booking", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionReopenInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdUnlinkBooking", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/booking-policy": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/booking-policy", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "serviceId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionBookingPolicyEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsBookingPolicy", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } }, "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/booking-policy", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionBookingPolicyInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionBookingPolicyCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsBookingPolicy", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/membership-options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/membership-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMembershipOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdMembershipOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/link-membership": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/link-membership", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionLinkMembershipInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdLinkMembership", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/unlink-membership": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/unlink-membership", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionReopenInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdUnlinkMembership", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/customer-options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/customer-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCustomerOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdCustomerOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/link-customer": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/link-customer", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionLinkCustomerInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdLinkCustomer", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/unlink-customer": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/unlink-customer", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionUnlinkCustomerInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdUnlinkCustomer", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/merge-options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/merge-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 160 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMergeOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdMergeOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/merge-preview": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/merge-preview", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "targetContactId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMergePreviewEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdMergePreview", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/merge-contact": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/merge-contact", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMergeContactInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager revision and UUID command; atomic history, minimal audit and durable Lead event. Erasure removes contact-owned data. No external provider, account, booking, money or membership side effect." } ] }, "operationId": "postApiV1LeadsByLeadIdMergeContact", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/phase-configuration": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/phase-configuration", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "version", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionPhaseConfigurationEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsPhaseConfiguration", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } }, "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/phase-configuration", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionPhaseConfigurationInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionPhaseConfigurationCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Owner/Manager expected-version and UUID command; immutable complete tenant configuration, minimal audit and replay receipt. No Lead rewrite or WorkflowEvent, booking, membership, money or consent side effect." } ] }, "operationId": "postApiV1LeadsPhaseConfiguration", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/assignee-options": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/leads/{leadId}/assignee-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionAssigneeOptionsEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadsByLeadIdAssigneeOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/leads/{leadId}/assignment": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/leads/{leadId}/assignment", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionAssignmentInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Explicit membership-bound assignment/revocation by live Owner/Manager or scoped API credential, Lead/member snapshots, actor-bound UUID, minimal history/audit/activity; no implicit access after reinvite." } ] }, "operationId": "postApiV1LeadsByLeadIdAssignment", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-work": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/lead-work", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "in": "query", "name": "stage", "required": false, "schema": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionWorkPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadWork", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-work/{leadId}": { "get": { "summary": "Tenant-bound acquisition GET /api/v1/lead-work/{leadId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionWorkDetailEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadWorkByLeadId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-work/{leadId}/move": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/lead-work/{leadId}/move", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionMoveInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionWorkCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Personally assigned operational command; live member/User/entitlement and assignment before replay. Existing semantic and Booking guards; minimal projection, history, audit, durable activity, no customer/finance/consent/provider authority." } ] }, "operationId": "postApiV1LeadWorkByLeadIdMove", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-work/{leadId}/close": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/lead-work/{leadId}/close", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionCloseInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionWorkCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Personally assigned operational command; live member/User/entitlement and assignment before replay. Existing semantic and Booking guards; minimal projection, history, audit, durable activity, no customer/finance/consent/provider authority." } ] }, "operationId": "postApiV1LeadWorkByLeadIdClose", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-work/{leadId}/reopen": { "post": { "summary": "Tenant-bound acquisition POST /api/v1/lead-work/{leadId}/reopen", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "leadId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionReopenInput" } } } }, "responses": { "200": { "description": "Bounded real tenant acquisition result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionWorkCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-lead-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Personally assigned operational command; live member/User/entitlement and assignment before replay. Existing semantic and Booking guards; minimal projection, history, audit, durable activity, no customer/finance/consent/provider authority." } ] }, "operationId": "postApiV1LeadWorkByLeadIdReopen", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-tasks": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-tasks", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "leadId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string", "enum": [ "open", "assigned", "completed", "cancelled" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTasks", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } }, "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-tasks", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCreateInput" } } } }, "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTasks", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-tasks/{taskId}": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-tasks/{taskId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTasksByTaskId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/lead-tasks/{taskId}/assign": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-tasks/{taskId}/assign", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskAssignInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTasksByTaskIdAssign", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-tasks/{taskId}/snooze": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-tasks/{taskId}/snooze", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskSnoozeInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTasksByTaskIdSnooze", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-tasks/{taskId}/complete": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-tasks/{taskId}/complete", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCompleteInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTasksByTaskIdComplete", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-tasks/{taskId}/cancel": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-tasks/{taskId}/cancel", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCancelInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTasksByTaskIdCancel", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-task-work": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-task-work", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "leadId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string", "enum": [ "open", "assigned", "completed", "cancelled" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTaskWork", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-work/{taskId}": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-task-work/{taskId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTaskWorkByTaskId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-work/{taskId}/claim": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-task-work/{taskId}/claim", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskClaimInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTaskWorkByTaskIdClaim", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-work/{taskId}/snooze": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-task-work/{taskId}/snooze", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskSnoozeInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTaskWorkByTaskIdSnooze", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-work/{taskId}/complete": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-task-work/{taskId}/complete", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCompleteInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTaskWorkByTaskIdComplete", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-work/{taskId}/cancel": { "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-task-work/{taskId}/cancel", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCancelInput" } } } }, "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTaskWorkByTaskIdCancel", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/lead-task-circles": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-task-circles", "tags": [ "Acquisition" ], "parameters": [ { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskLocationPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTaskCircles", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/lead-task-circles/{locationId}": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-task-circles/{locationId}", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "locationId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCircleEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTaskCirclesByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } }, "post": { "summary": "Tenant-bound callback tasks POST /api/v1/lead-task-circles/{locationId}", "tags": [ "Acquisition" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCircleInput" } } } }, "parameters": [ { "in": "path", "name": "locationId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskCircleCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "acquisition-command", "description": "Current identity, operational grant or management scope before actor-bound UUID replay; CAS, task history/audit/outbox and explicit next callback commit atomically. Circle rotation never grants Customer/Lead/payment/consent authority; no provider send." } ] }, "operationId": "postApiV1LeadTaskCirclesByLocationId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "leads:write", "credentialName": "Authorization" } } }, "/api/v1/lead-task-circles/{locationId}/member-options": { "get": { "summary": "Tenant-bound callback tasks GET /api/v1/lead-task-circles/{locationId}/member-options", "tags": [ "Acquisition" ], "parameters": [ { "in": "path", "name": "locationId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "x-vsm-acquisition-tenant", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Confirmed tenant precondition; mismatch409, never authorization." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized callback state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquisitionTaskMemberPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-acquisition-contract": "vsm-acquisition-task-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LeadTaskCirclesByLocationIdMemberOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "leads:read", "credentialName": "Authorization" } } }, "/api/v1/participants": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/participants", "tags": [ "Families" ], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1Participants", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" } }, "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participants", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantCreateInput" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current identity/scope and override before actor-bound UUID replay; profile or exact identity-bound representation and receipt persist atomically. Confirmation is human operator-session-only and does not assert legal guardianship. No child login, implicit consent, Booking, credit debit or provider send." } ] }, "operationId": "postApiV1Participants", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" } } }, "/api/v1/participants/{participantId}": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/participants/{participantId}", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ParticipantsByParticipantId", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" } } }, "/api/v1/participants/{participantId}/representations": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/participants/{participantId}/representations", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ParticipantsByParticipantIdRepresentations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" } }, "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participants/{participantId}/representations", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationInput" } } } }, "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current identity/scope and override before actor-bound UUID replay; profile or exact identity-bound representation and receipt persist atomically. Confirmation is human operator-session-only and does not assert legal guardianship. No child login, implicit consent, Booking, credit debit or provider send." } ] }, "operationId": "postApiV1ParticipantsByParticipantIdRepresentations", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" } } }, "/api/v1/participant-representations/{representationId}/confirm": { "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participant-representations/{representationId}/confirm", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationConfirmInput" } } } }, "parameters": [ { "in": "path", "name": "representationId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current identity/scope and override before actor-bound UUID replay; profile or exact identity-bound representation and receipt persist atomically. Confirmation is human operator-session-only and does not assert legal guardianship. No child login, implicit consent, Booking, credit debit or provider send." } ] }, "operationId": "postApiV1ParticipantRepresentationsByRepresentationIdConfirm", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/participant-representations/{representationId}/revoke": { "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participant-representations/{representationId}/revoke", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationRevokeInput" } } } }, "parameters": [ { "in": "path", "name": "representationId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentationCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current identity/scope and override before actor-bound UUID replay; profile or exact identity-bound representation and receipt persist atomically. Confirmation is human operator-session-only and does not assert legal guardianship. No child login, implicit consent, Booking, credit debit or provider send." } ] }, "operationId": "postApiV1ParticipantRepresentationsByRepresentationIdRevoke", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" } } }, "/api/v1/customer-account/{tenantSlug}/participants": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/customer-account/{tenantSlug}/participants", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalFamilyParticipantPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CustomerAccountByTenantSlugParticipants", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/customer-account/{tenantSlug}/participants/{participantId}": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/customer-account/{tenantSlug}/participants/{participantId}", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalFamilyParticipantEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CustomerAccountByTenantSlugParticipantsByParticipantId", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/participants/{participantId}/representative-options": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/participants/{participantId}/representative-options", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyRepresentativeOptionPageEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ParticipantsByParticipantIdRepresentativeOptions", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" } } }, "/api/v1/customer-account/{tenantSlug}/participant-bookings": { "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/customer-account/{tenantSlug}/participant-bookings", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyBookingInput" } } } }, "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyBookingResultEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Personal verified session only. Recheck current exact book grants/entitlements before canonical actor-bound UUID replay; normalized same-tenant links, existing capacity and optional payer-owned membership debit commit atomically. Confirmation mail goes to the server-resolved verified adult and rechecks authority. No child account or email and no standalone self-service capability." } ] }, "operationId": "postApiV1CustomerAccountByTenantSlugParticipantBookings", "security": [ { "customerSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/participants/{participantId}/export": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/participants/{participantId}/export", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantExportEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ParticipantsByParticipantIdExport", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "customers:read", "credentialName": "Authorization" } } }, "/api/v1/participants/{participantId}/archive": { "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participants/{participantId}/archive", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantRevisionInput" } } } }, "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current authorized operator identity/scope, CAS and actor-bound UUID. Archive profile and permanently revoke current/pending representations atomically; cancel and scrub queued/failed related mail. Preserve Booking links, partySize/status and accounting. A PROCESSING mail lease fails closed before mutation." } ] }, "operationId": "postApiV1ParticipantsByParticipantIdArchive", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "customers:write", "credentialName": "Authorization" } } }, "/api/v1/participants/{participantId}/erase": { "post": { "summary": "Explicit tenant-bound family participants POST /api/v1/participants/{participantId}/erase", "tags": [ "Families" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantErasureInput" } } } }, "parameters": [ { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantErasureCommandEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "participant-command", "description": "Current human Owner session only. CAS and actor-bound UUID commit subject tombstone, grant/link deletion and input/mail/notes redaction atomically. Preserve Booking partySize/status/original adult and accounting debit; downgrade named-set completeness only. A PROCESSING mail lease fails closed before mutation. No automatic child-retention policy or provider action." } ] }, "operationId": "postApiV1ParticipantsByParticipantIdErase", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/customer-account/{tenantSlug}/participants/{participantId}/export": { "get": { "summary": "Explicit tenant-bound family participants GET /api/v1/customer-account/{tenantSlug}/participants/{participantId}/export", "tags": [ "Families" ], "parameters": [ { "in": "path", "name": "tenantSlug", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "participantId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Current authorized participant projection or command receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyParticipantExportEnvelope" } } } }, "400": { "description": "BAD_REQUEST", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "ENTITLEMENT_REQUIRED", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "CONFLICT", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "EXTERNAL_SERVICE_NOT_CONFIGURED", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-participant-contract": "vsm-family-participant-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "families.participants", "features": [ "families.participants" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "BAD_REQUEST" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "UNAUTHORIZED" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "ENTITLEMENT_REQUIRED" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "FORBIDDEN" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "NOT_FOUND" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "CONFLICT" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "PAYLOAD_TOO_LARGE" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "VALIDATION_ERROR" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "RATE_LIMITED" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "EXTERNAL_SERVICE_NOT_CONFIGURED" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1CustomerAccountByTenantSlugParticipantsByParticipantIdExport", "security": [ { "customerSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "customerSession", "allowedPrincipals": [ "customer-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages": { "get": { "summary": "List offer landing pages", "tags": [ "Reporting" ], "responses": { "200": { "description": "F19 landing pages of the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LandingPages", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Create an offer landing page draft", "tags": [ "Reporting" ], "responses": { "200": { "description": "F19 page created with a DRAFT version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageCreateInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "landing_page.* audit event in the same transaction" } ] }, "operationId": "postApiV1LandingPages", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/{pageId}": { "get": { "summary": "Read one offer landing page", "tags": [ "Reporting" ], "responses": { "200": { "description": "F19 page with draft and published snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LandingPagesByPageId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/{pageId}/draft": { "post": { "summary": "Save the landing page draft", "tags": [ "Reporting" ], "responses": { "200": { "description": "Revision-fenced draft save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageDraftInput" } } } }, "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "landing_page.* audit event in the same transaction" } ] }, "operationId": "postApiV1LandingPagesByPageIdDraft", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/{pageId}/publish": { "post": { "summary": "Publish the landing page after a live source check", "tags": [ "Reporting" ], "responses": { "200": { "description": "Publishes the draft after a live source check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageCommandInput" } } } }, "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "landing_page.* audit event in the same transaction" } ] }, "operationId": "postApiV1LandingPagesByPageIdPublish", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/{pageId}/unpublish": { "post": { "summary": "Withdraw the landing page", "tags": [ "Reporting" ], "responses": { "200": { "description": "Withdraws the page from public reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageCommandInput" } } } }, "parameters": [ { "name": "pageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "landing_page.* audit event in the same transaction" } ] }, "operationId": "postApiV1LandingPagesByPageIdUnpublish", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/media-options": { "get": { "summary": "List tenant images for landing pages", "tags": [ "Reporting" ], "responses": { "200": { "description": "READY tenant images usable on landing pages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageMediaOptionsEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LandingPagesMediaOptions", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Upload a tenant image for landing pages", "tags": [ "Reporting" ], "responses": { "200": { "description": "F19 tenant image upload (multipart file; JPEG/PNG/WebP sniffed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageMediaUploadEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "landing_page.media_uploaded; encrypted media object stored" } ] }, "operationId": "postApiV1LandingPagesMediaOptions", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/landing-pages/media-options/{assetId}": { "get": { "summary": "Operator preview of a landing page image", "tags": [ "Reporting" ], "responses": { "200": { "description": "Operator-only no-store image preview", "content": { "image/*": { "schema": { "$ref": "#/components/schemas/LandingPageMediaArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1LandingPagesMediaOptionsByAssetId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/public/{tenantSlug}/landing-pages/{slug}": { "get": { "summary": "Read a published offer landing page", "tags": [ "Public Booking" ], "responses": { "200": { "description": "Live public landing page; any miss is 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicLandingPageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "tenantSlug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "embeds.website", "features": [ "embeds.website" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiPublicByTenantSlugLandingPagesBySlug", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/v1/follow-up-sequences": { "get": { "summary": "List follow-up sequences", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 list follow-up sequences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1FollowUpSequences", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Create a follow-up sequence", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 create a follow-up sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceCreateInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequences", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/revise": { "post": { "summary": "Create a new sequence version", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 create a new sequence version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceReviseInput" } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequencesBySequenceIdRevise", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/status": { "post": { "summary": "Activate, pause or archive a sequence", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 activate, pause or archive a sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpSequenceStatusInput" } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequencesBySequenceIdStatus", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/migrate": { "post": { "summary": "Preview or apply moving running enrollments to the current version", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 preview or apply moving running enrollments to the current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpMigrationEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpMigrateInput" } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequencesBySequenceIdMigrate", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/preview": { "get": { "summary": "Preview the reactivation audience", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 preview the reactivation audience", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpPreviewEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1FollowUpSequencesBySequenceIdPreview", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/enroll": { "post": { "summary": "Enroll the previewed reactivation audience", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 enroll the previewed reactivation audience", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpEnrollResultEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpEnrollInput" } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequencesBySequenceIdEnroll", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/{sequenceId}/enrollments": { "get": { "summary": "List enrollments of a sequence", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 list enrollments of a sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpEnrollmentListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1FollowUpSequencesBySequenceIdEnrollments", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/follow-up-sequences/enrollments/{enrollmentId}": { "post": { "summary": "Pause, resume, snooze, stop or mark an enrollment replied", "tags": [ "Reporting" ], "responses": { "200": { "description": "F08 pause, resume, snooze, stop or mark an enrollment replied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpEnrollmentEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpEnrollmentCommandInput" } } } }, "parameters": [ { "name": "enrollmentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "follow_up.* audit event in the same transaction" } ] }, "operationId": "postApiV1FollowUpSequencesEnrollmentsByEnrollmentId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/attribution-report": { "get": { "summary": "First-party source report (first touch and last non-direct touch)", "tags": [ "Reporting" ], "responses": { "200": { "description": "F17 first-party source report with named model, lookback and unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionReportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AttributionReport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/operator-push": { "get": { "summary": "List this operator's active push devices", "tags": [ "Reporting" ], "responses": { "200": { "description": "F14 list this operator's active push devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushDeviceListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1OperatorPush", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Register this browser for operator notifications", "tags": [ "Reporting" ], "responses": { "200": { "description": "F14 register this browser for operator notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushDeviceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushRegisterInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "deviceRegistry", "description": "Operator push device created, updated or revoked" } ] }, "operationId": "postApiV1OperatorPush", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/operator-push/{deviceId}": { "patch": { "summary": "Change notification categories", "tags": [ "Reporting" ], "responses": { "200": { "description": "F14 change notification categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushDeviceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushCategoriesInput" } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "deviceRegistry", "description": "Operator push device created, updated or revoked" } ] }, "operationId": "patchApiV1OperatorPushByDeviceId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } }, "delete": { "summary": "Turn off notifications on a device", "tags": [ "Reporting" ], "responses": { "200": { "description": "F14 turn off notifications on a device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPushDeviceEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "deviceRegistry", "description": "Operator push device created, updated or revoked" } ] }, "operationId": "deleteApiV1OperatorPushByDeviceId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/ad-spend/imports": { "post": { "summary": "Preview or apply an ad spend CSV import", "tags": [ "Reporting" ], "responses": { "200": { "description": "F18 preview or apply an ad spend csv import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdSpendImportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdSpendImportInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "ad_spend.imported audit event when applied" } ] }, "operationId": "postApiV1AdSpendImports", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/ad-spend/report": { "get": { "summary": "Cost per won contact and opportunity by campaign and currency", "tags": [ "Reporting" ], "responses": { "200": { "description": "F18 cost per won contact and opportunity by campaign and currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdSpendReportEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "acquisition.pipeline", "features": [ "acquisition.pipeline" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdSpendReport", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/support-console/step-up": { "get": { "summary": "Read the staff MFA step-up state of the current session", "tags": [ "Admin", "Support" ], "responses": { "200": { "description": "Step-up state bound to session and grant revision", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Session missing or MFA step-up code invalid or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform support grant, tenant scope, browser session, CSRF or step-up missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Database persistence is not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminSupportConsoleStepUp", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Confirm staff access with a fresh single-use TOTP code", "tags": [ "Admin", "Support" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 16 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Step-up granted for 15 minutes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Session missing or MFA step-up code invalid or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform support grant, tenant scope, browser session, CSRF or step-up missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Too many failed confirmations", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Database persistence is not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminSupportConsoleStepUp", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/support-console/diagnosis": { "get": { "summary": "Tenant-scoped order, ticket, webhook and mail diagnosis", "tags": [ "Admin", "Support" ], "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Redacted diagnosis without buyer, content, provider or payment secrets", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Session missing or MFA step-up code invalid or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform support grant, tenant scope, browser session, CSRF or step-up missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant or reference not found for this tenant", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Database persistence is not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "getApiV1AdminSupportConsoleDiagnosis", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/support-console/orders/{orderId}/resend-ticket-mail": { "post": { "summary": "Resend the ticket mail once per staff intent", "tags": [ "Admin", "Support" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId", "intentId", "reason", "expectedOrderVersion" ], "properties": { "tenantId": { "type": "string" }, "intentId": { "type": "string", "minLength": 16, "maxLength": 160 }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 }, "expectedOrderVersion": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Audited command result; repeated intents return the recorded result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Session missing or MFA step-up code invalid or replayed", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform support grant, tenant scope, browser session, CSRF or step-up missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Order not found for this tenant", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Stale order version, ineligible order or reused intent", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Request is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Database persistence is not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiV1AdminSupportConsoleOrdersByOrderIdResendTicketMail", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-senders": { "get": { "summary": "List SMS/WhatsApp senders", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 list SMS/WhatsApp sender numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSenderListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.sms", "features": [ "communication.sms" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1TextSenders", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Register an SMS/WhatsApp sender", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 register a provider sender number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSenderEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSenderCreateInput" } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.sms", "features": [ "communication.sms" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_sender.created audit event" } ] }, "operationId": "postApiV1TextSenders", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-senders/{senderId}/status": { "post": { "summary": "Activate or disable a sender", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 activate or disable a sender (CAS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSenderEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSenderStatusInput" } } } }, "parameters": [ { "name": "senderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.sms", "features": [ "communication.sms" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_sender.active|disabled audit event" } ] }, "operationId": "postApiV1TextSendersBySenderIdStatus", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-messages": { "get": { "summary": "List SMS/WhatsApp messages", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 messages of a visible thread or unassigned inbound messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextMessageListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "threadId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "unassigned", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": null, "features": [ "communication.sms", "communication.whatsapp" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1TextMessages", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Queue an SMS/WhatsApp message", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 queue an SMS/WhatsApp message (replay returns the original)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextMessageQueuedEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextMessageSendInput" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TextMessageMediaSendInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": null, "features": [ "communication.sms", "communication.whatsapp" ], "mode": "conditional" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_message.queued audit event" }, { "kind": "worker", "description": "Worker reserves one usage unit and hands the message to Twilio" } ] }, "operationId": "postApiV1TextMessages", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-messages/{messageId}/assign": { "post": { "summary": "Assign an inbound message to a thread", "tags": [ "Reporting" ], "responses": { "200": { "description": "F05/F06 assign an unassigned inbound message to a thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextMessageEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextMessageAssignInput" } } } }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.sms", "features": [ "communication.sms" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_message.assigned audit event" } ] }, "operationId": "postApiV1TextMessagesByMessageIdAssign", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-messages/{messageId}/media/{mediaId}": { "get": { "summary": "Download inbound WhatsApp media", "tags": [ "Reporting" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "F06 authorized inbound Twilio or encrypted outbound media bytes (no-store attachment)", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/TextMessageMediaArtifact" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "The tenant-scoped export job or reconciliation was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "The tenant-scoped export job or reconciliation was not found" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1TextMessagesByMessageIdMediaByMediaId", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/whatsapp-templates": { "get": { "summary": "List WhatsApp templates", "tags": [ "Reporting" ], "responses": { "200": { "description": "F06 list the tenant's WhatsApp templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1WhatsappTemplates", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Create a WhatsApp template reference", "tags": [ "Reporting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateInput" } } } }, "responses": { "200": { "description": "F06 reference an approved-to-be Twilio Content template (starts pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "whatsapp_template.created audit event" } ] }, "operationId": "postApiV1WhatsappTemplates", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/whatsapp-templates/{templateId}": { "patch": { "summary": "Edit a WhatsApp template", "tags": [ "Reporting" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateUpdateInput" } } } }, "responses": { "200": { "description": "F06 edit a template (content change: new version, back to pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "whatsapp_template.updated audit event" } ] }, "operationId": "patchApiV1WhatsappTemplatesByTemplateId", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/whatsapp-templates/{templateId}/status": { "post": { "summary": "Set the WhatsApp template approval status", "tags": [ "Reporting" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateStatusInput" } } } }, "responses": { "200": { "description": "F06 set the approval status maintained from the Twilio console (CAS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppTemplateEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "whatsapp_template.status_changed audit event" } ] }, "operationId": "postApiV1WhatsappTemplatesByTemplateIdStatus", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-opt-ins": { "get": { "summary": "List opt-ins of a thread counterpart", "tags": [ "Reporting" ], "parameters": [ { "name": "threadId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sms", "whatsapp" ] } } ], "responses": { "200": { "description": "F06 purpose-bound opt-ins of a visible thread's counterpart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOptInListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1TextOptIns", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Record operator opt-in with evidence", "tags": [ "Reporting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOptInRecordInput" } } } }, "responses": { "200": { "description": "F06 record operator consent with evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOptInListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_opt_in.recorded audit event per purpose" } ] }, "operationId": "postApiV1TextOptIns", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/text-opt-ins/{optInId}/revoke": { "post": { "summary": "Revoke an opt-in", "tags": [ "Reporting" ], "parameters": [ { "name": "optInId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOptInRevokeInput" } } } }, "responses": { "200": { "description": "F06 revoke an opt-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOptInEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "communication.whatsapp", "features": [ "communication.whatsapp" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "text_opt_in.revoked audit event" } ] }, "operationId": "postApiV1TextOptInsByOptInIdRevoke", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/public/text/media/{mediaId}": { "get": { "summary": "Read one private WhatsApp attachment using the short-lived provider capability", "tags": [ "Communication" ], "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^tmc_[A-Za-z0-9_-]{43}$", "minLength": 47, "maxLength": 47 } } ], "responses": { "200": { "description": "F06 one outbound attachment authorized by the current short-lived provider capability; HEAD has no body", "content": { "image/jpeg": { "schema": { "$ref": "#/components/schemas/TextMessageMediaArtifact" } }, "image/png": { "schema": { "$ref": "#/components/schemas/TextMessageMediaArtifact" } }, "application/pdf": { "schema": { "$ref": "#/components/schemas/TextMessageMediaArtifact" } } } }, "404": { "description": "Missing, invalid, expired or revoked attachment capability", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Bounded provider media reads", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Private media storage or rate limiter unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Missing, invalid, expired or revoked attachment capability" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Bounded provider media reads" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Private media storage or rate limiter unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiPublicTextMediaByMediaId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "resourceToken", "allowedPrincipals": [ "provider-media-token" ], "credentialLocation": "query", "csrfRequiredForCookieSession": false, "credentialName": "token" } }, "head": { "summary": "Read the headers of one private WhatsApp attachment using the short-lived provider capability", "tags": [ "Communication" ], "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^tmc_[A-Za-z0-9_-]{43}$", "minLength": 47, "maxLength": 47 } } ], "responses": { "200": { "description": "F06 one outbound attachment authorized by the current short-lived provider capability; HEAD has no body" }, "404": { "description": "Missing, invalid, expired or revoked attachment capability", "x-vsm-error-codes": [ "NOT_FOUND" ] }, "429": { "description": "Bounded provider media reads", "x-vsm-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Private media storage or rate limiter unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ] } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Missing, invalid, expired or revoked attachment capability" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Bounded provider media reads" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Private media storage or rate limiter unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "headApiPublicTextMediaByMediaId", "security": [], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "resourceToken", "allowedPrincipals": [ "provider-media-token" ], "credentialLocation": "query", "csrfRequiredForCookieSession": false, "credentialName": "token" } } }, "/api/public/text/twilio/inbound": { "post": { "summary": "Twilio inbound SMS/WhatsApp webhook", "tags": [ "Public" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Empty TwiML acknowledgement", "content": { "text/xml": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid X-Twilio-Signature", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body too large", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Not a Twilio form body", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Twilio or persistence not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTextTwilioInbound", "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/public/text/twilio/status": { "post": { "summary": "Twilio message status callback", "tags": [ "Public" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "responses": { "204": { "description": "Status recorded or ignored" }, "401": { "description": "Missing or invalid X-Twilio-Signature", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body too large", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Not a Twilio form body", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Twilio or persistence not configured", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "operationId": "postApiPublicTextTwilioStatus", "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "public", "allowedPrincipals": [ "public" ], "credentialLocation": "none", "csrfRequiredForCookieSession": false } } }, "/api/v1/service-requests": { "get": { "summary": "List service requests", "tags": [ "Reporting" ], "responses": { "200": { "description": "F21 list the tenant's service requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequestListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1ServiceRequests", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Request a personal service", "tags": [ "Reporting" ], "responses": { "200": { "description": "F21 request onboarding, review or integration service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequestEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRequestCreateInput" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "tenant.core", "features": [ "tenant.core" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "service_request.created audit event" }, { "kind": "mail", "description": "Platform notice to VSM_BOOKING_SERVICE_REQUEST_EMAIL when configured" } ] }, "operationId": "postApiV1ServiceRequests", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/usage-billing-corrections": { "get": { "summary": "List submitted usage billing exports with their prepared and executed corrections", "tags": [ "Admin", "Billing" ], "responses": { "200": { "description": "Submitted exports (latest 100) with corrections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBillingCorrectionListEnvelope" } } } }, "401": { "description": "Platform admin session is missing", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform role lacks the billing correction capability", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.billingCorrections.read", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform admin session is missing" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform role lacks the billing correction capability" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1AdminUsageBillingCorrections", "security": [ { "platformAdminSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } }, "post": { "summary": "Prepare a usage correction (credit note for a finalized invoice, otherwise meter adjustment) without changing Stripe", "tags": [ "Admin", "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBillingCorrectionPrepareInput" } } } }, "responses": { "200": { "description": "Prepared correction with the previewed credit amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBillingCorrectionEnvelope" } } } }, "400": { "description": "Request body is not valid JSON", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Platform admin session is missing", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform role lacks the billing correction capability", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Usage billing export or correction was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Quantity or reason is invalid or exceeds the billed quantity", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe or the usage meter is not configured or Stripe failed (sanitized)", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.billingCorrections.write", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body is not valid JSON" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform admin session is missing" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform role lacks the billing correction capability" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Usage billing export or correction was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Quantity or reason is invalid or exceeds the billed quantity" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe or the usage meter is not configured or Stripe failed (sanitized)" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-read", "description": "Reads Stripe meter, prices, invoices and a credit note preview; no Stripe mutation" }, { "kind": "persistence", "description": "Creates a prepared UsageBillingCorrection" }, { "kind": "audit", "description": "Writes usage_correction.prepared" } ] }, "operationId": "postApiV1AdminUsageBillingCorrections", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/usage-billing-corrections/{correctionId}/approve": { "post": { "summary": "Manually approve and execute a prepared usage correction once", "tags": [ "Admin", "Billing" ], "parameters": [ { "name": "correctionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Executed correction; a repeated approval returns replayed=true without a Stripe call", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBillingCorrectionApprovalEnvelope" } } } }, "401": { "description": "Platform admin session is missing", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform role lacks the billing correction capability", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Usage billing export or correction was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe or the usage meter is not configured or Stripe failed (sanitized)", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.billingCorrections.approve", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform admin session is missing" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform role lacks the billing correction capability" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Usage billing export or correction was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe or the usage meter is not configured or Stripe failed (sanitized)" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "stripe", "description": "Creates one Stripe credit note (idempotency key, no automatic refund) or cancels/replaces the meter event", "conditional": true }, { "kind": "persistence", "description": "Marks the correction executed or failed" }, { "kind": "audit", "description": "Writes usage_correction.approved and executed/failed" } ] }, "operationId": "postApiV1AdminUsageBillingCorrectionsByCorrectionIdApprove", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/usage-billing-corrections/{correctionId}/cancel": { "post": { "summary": "Discard a correction without Stripe effects (a failed credit note is reconciled with Stripe first)", "tags": [ "Admin", "Billing" ], "parameters": [ { "name": "correctionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "responses": { "200": { "description": "Cancelled correction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBillingCorrectionEnvelope" } } } }, "401": { "description": "Platform admin session is missing", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Platform role lacks the billing correction capability", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Usage billing export or correction was not found", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Stripe could not be checked (sanitized)", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.billingCorrections.write", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform admin session is missing" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Platform role lacks the billing correction capability" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Usage billing export or correction was not found" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Export not submitted, correction already open, invoice voided/finalized since preparation, amount changed or meter timestamp expired" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Stripe could not be checked (sanitized)" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "external-read", "description": "For a failed credit note: lists the invoice's credit notes; a found note marks the case executed", "conditional": true }, { "kind": "persistence", "description": "Marks the correction cancelled" }, { "kind": "audit", "description": "Writes usage_correction.cancelled" } ] }, "operationId": "postApiV1AdminUsageBillingCorrectionsByCorrectionIdCancel", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/holiday-imports/proposals": { "get": { "summary": "List pending annual holiday refresh proposals of a calendar with a live conflict preview", "tags": [ "Communication" ], "responses": { "200": { "description": "F13 pending annual refresh proposals of one calendar with a live conflict preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportProposalListEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "parameters": [ { "name": "calendarId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ], "default": "de" } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1HolidayImportsProposals", "security": [ { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": false, "credentialName": "vsm_booking_session" } } }, "/api/v1/holiday-imports/proposals/{proposalId}/accept": { "post": { "summary": "Accept an annual holiday refresh proposal and apply its reviewed snapshot", "tags": [ "Communication" ], "responses": { "200": { "description": "Applies the reviewed snapshot through the optimistic holiday import apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportProposalDecisionEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportProposalAcceptInput" } } } }, "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "calendar.holiday_import_proposal_accepted (and calendar.holiday_import_applied when exceptions change) in the same transaction" } ] }, "operationId": "postApiV1HolidayImportsProposalsByProposalIdAccept", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/holiday-imports/proposals/{proposalId}/dismiss": { "post": { "summary": "Dismiss an annual holiday refresh proposal without changing the calendar", "tags": [ "Communication" ], "responses": { "200": { "description": "Dismisses the proposal without changing the calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportProposalDecisionEnvelope" } } } }, "401": { "description": "Authenticated operator session is required", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "The tenant lacks the required reporting feature", "x-vsm-error-codes": [ "ENTITLEMENT_REQUIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Only tenant Owner or Manager may access operational reports", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Idempotency or current export lifecycle state conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "The JSON request body exceeds the endpoint limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "The report window, filter, pagination, or export input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "The operator request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized report, artifact integrity, or persistence failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL or private export storage is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HolidayImportProposalDismissInput" } } } }, "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 160 } } ], "x-vsm-reporting-contract": "vsm-reporting-export-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": true, "feature": "calendar.booking", "features": [ "calendar.booking" ] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Authenticated operator session is required" }, { "status": 402, "codes": [ "ENTITLEMENT_REQUIRED" ], "description": "The tenant lacks the required reporting feature" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Only tenant Owner or Manager may access operational reports" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Idempotency or current export lifecycle state conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "The JSON request body exceeds the endpoint limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "The report window, filter, pagination, or export input is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "The operator request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized report, artifact integrity, or persistence failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL or private export storage is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "audit", "description": "calendar.holiday_import_proposal_dismissed in the same transaction" } ] }, "operationId": "postApiV1HolidayImportsProposalsByProposalIdDismiss", "security": [ { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "session", "allowedPrincipals": [ "operator-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" } } }, "/api/v1/admin/provider-controls/{provider}/verify": { "post": { "summary": "Request non-sending delivery provider verification", "tags": [ "Admin", "Operations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryProviderRecoveryInput" } } } }, "responses": { "200": { "description": "Pending connection verification or replayed terminal command; never a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryProviderRecoveryEnvelope" } } } }, "202": { "description": "Pending connection verification or replayed terminal command; never a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryProviderRecoveryEnvelope" } } } }, "401": { "description": "Platform Admin session is missing or invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Required global Platform Admin capability is missing", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Protected, duplicate, ineligible, or revoked target conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Query, role, expiry, identifier, or reason input is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Required Prisma persistence is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-required-capability": "admin.quality.write", "operationId": "postApiV1AdminProviderControlsByProviderVerify", "security": [ { "platformAdminSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "platformAdmin", "allowedPrincipals": [ "platform-admin-session" ], "credentialLocation": "http-only-cookie", "csrfRequiredForCookieSession": true, "credentialName": "vsm_booking_session" }, "x-vsm-platform-admin-operations-contract": "vsm-platform-admin-operations-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [], "mode": "all" }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Platform Admin session is missing or invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Required global Platform Admin capability is missing" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Query, role, expiry, identifier, or reason input is invalid" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Protected, duplicate, ineligible, or revoked target conflicts" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "Required Prisma persistence is unavailable" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "provider-recovery-command", "description": "Persists an audited revision-bound connection check; the existing Worker verifies AUTH/Account GET without a message before atomically enabling delivery" } ] }, "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "smtp", "twilio" ] } } ], "description": "Persist a reasoned, revision-bound non-sending SMTP/Twilio connection check for the existing Worker; request acceptance is pending, and only a verified current command can enable delivery." } }, "/api/v1/tenant-branding": { "get": { "summary": "Read tenant branding", "tags": [ "Tenants" ], "responses": { "200": { "description": "Current tenant logo, colors and booking-form preference only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBrandingEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [] }, "operationId": "getApiV1TenantBranding", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": false, "requiredScope": "branding:read", "credentialName": "Authorization" } }, "patch": { "summary": "Update tenant branding", "tags": [ "Tenants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBrandingInput" } } } }, "responses": { "200": { "description": "Merged tenant branding; other tenant metadata is preserved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBrandingEnvelope" } } } }, "400": { "description": "Request body or tenant context cannot be parsed", "x-vsm-error-codes": [ "BAD_REQUEST" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Operator, Platform Admin, or API credential is invalid", "x-vsm-error-codes": [ "UNAUTHORIZED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Tenant, role, plan mutation, or API scope denies access", "x-vsm-error-codes": [ "FORBIDDEN" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Tenant, member, or Location was not found in the caller scope", "x-vsm-error-codes": [ "NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Slug, member, final-owner, active resource, or reference invariant conflicts", "x-vsm-error-codes": [ "CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Request body exceeds the endpoint payload limit", "x-vsm-error-codes": [ "PAYLOAD_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Body, path, cursor, pagination, locale, or timezone is invalid", "x-vsm-error-codes": [ "VALIDATION_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Credential request quota is exhausted", "x-vsm-error-codes": [ "RATE_LIMITED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Sanitized internal failure", "x-vsm-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "PostgreSQL, auth-token, or mail runtime is unavailable", "x-vsm-error-codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } }, "x-vsm-tenant-location-contract": "vsm-tenant-location-contract-v1", "x-vsm-entitlement": { "contractVersion": "vsm-entitlement-v1", "required": false, "feature": null, "features": [] }, "x-vsm-errors": { "contractVersion": "vsm-errors-v1", "cases": [ { "status": 400, "codes": [ "BAD_REQUEST" ], "description": "Request body or tenant context cannot be parsed" }, { "status": 401, "codes": [ "UNAUTHORIZED" ], "description": "Operator, Platform Admin, or API credential is invalid" }, { "status": 403, "codes": [ "FORBIDDEN" ], "description": "Tenant, role, plan mutation, or API scope denies access" }, { "status": 404, "codes": [ "NOT_FOUND" ], "description": "Tenant, member, or Location was not found in the caller scope" }, { "status": 409, "codes": [ "CONFLICT" ], "description": "Slug, member, final-owner, active resource, or reference invariant conflicts" }, { "status": 413, "codes": [ "PAYLOAD_TOO_LARGE" ], "description": "Request body exceeds the endpoint payload limit" }, { "status": 422, "codes": [ "VALIDATION_ERROR" ], "description": "Body, path, cursor, pagination, locale, or timezone is invalid" }, { "status": 429, "codes": [ "RATE_LIMITED" ], "description": "Credential request quota is exhausted" }, { "status": 500, "codes": [ "INTERNAL_ERROR" ], "description": "Sanitized internal failure" }, { "status": 503, "codes": [ "EXTERNAL_SERVICE_NOT_CONFIGURED" ], "description": "PostgreSQL, auth-token, or mail runtime is unavailable" } ] }, "x-vsm-side-effects": { "contractVersion": "vsm-side-effects-v1", "effects": [ { "kind": "persistence", "description": "Merges logo, colors and booking-form keys into Tenant branding" }, { "kind": "audit", "description": "Records tenant.branding.updated with auth mode, credential id and changed keys only" } ] }, "operationId": "patchApiV1TenantBranding", "security": [ { "apiKeyBearer": [] }, { "operatorSession": [], "csrfToken": [] } ], "x-vsm-access": { "contractVersion": "vsm-openapi-access-v1", "kind": "apiKey", "allowedPrincipals": [ "api-key", "operator-session" ], "credentialLocation": "authorization-header", "csrfRequiredForCookieSession": true, "requiredScope": "branding:write", "credentialName": "Authorization" } } } }, "components": { "schemas": { "VenueProfileCategory": { "type": "string", "enum": [ "yoga", "fitness", "wellness", "gastronomy", "culture", "music", "leisure", "education", "consulting", "retail", "other" ] }, "VenueProfilePublicModule": { "type": "string", "enum": [ "booking", "events", "tickets", "coupons" ] }, "VenueProfileOpeningPeriod": { "type": "object", "additionalProperties": false, "required": [ "opens", "closes" ], "properties": { "opens": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "closes": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } } }, "VenueProfileOpeningDay": { "type": "object", "additionalProperties": false, "required": [ "day", "periods" ], "properties": { "day": { "$ref": "#/components/schemas/VenueProfileWeekday" }, "periods": { "type": "array", "maxItems": 8, "uniqueItems": false, "items": { "$ref": "#/components/schemas/VenueProfileOpeningPeriod" } } } }, "VenueProfileDraft": { "type": "object", "additionalProperties": false, "required": [ "name", "tagline", "description", "categories", "openingHours", "address", "contact", "coordinates", "timezone", "publicModules" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "tagline": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "categories": { "type": "array", "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/VenueProfileCategory" } }, "openingHours": { "type": "array", "maxItems": 7, "uniqueItems": false, "items": { "$ref": "#/components/schemas/VenueProfileOpeningDay" } }, "address": { "$ref": "#/components/schemas/VenueProfileAddress" }, "contact": { "$ref": "#/components/schemas/VenueProfileContact" }, "coordinates": { "$ref": "#/components/schemas/VenueProfileCoordinates" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "publicModules": { "type": "array", "maxItems": 4, "uniqueItems": true, "items": { "$ref": "#/components/schemas/VenueProfilePublicModule" } } } }, "VenueProfileDraftSaveInput": { "type": "object", "additionalProperties": false, "required": [ "expectedDraftRevision", "profile" ], "properties": { "expectedDraftRevision": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "profile": { "$ref": "#/components/schemas/VenueProfileDraft" } } }, "VenueProfilePublishInput": { "type": "object", "additionalProperties": false, "required": [ "expectedDraftRevision" ], "properties": { "expectedDraftRevision": { "type": "integer", "minimum": 1 } } }, "VenueProfileArchiveInput": { "type": "object", "additionalProperties": false, "required": [ "expectedProfileUpdatedAt" ], "properties": { "expectedProfileUpdatedAt": { "type": "string", "format": "date-time" } } }, "VenueProfileAdminProjection": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "location", "profile", "permissions" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-venue-profile-admin-v1" }, "location": { "$ref": "#/components/schemas/VenueProfileLocationSummary" }, "profile": { "$ref": "#/components/schemas/VenueProfileAdminState" }, "permissions": { "$ref": "#/components/schemas/VenueProfilePermissions" } } }, "PublicVenueProfileProjection": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "profile", "modules" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-venue-profile-v1" }, "profile": { "$ref": "#/components/schemas/PublicVenueProfile" }, "modules": { "$ref": "#/components/schemas/VenueProfileModuleMap" } } }, "PlatformAdminRole": { "type": "string", "enum": [ "superAdmin", "operationsAdmin", "supportAdmin", "readOnlyAuditor" ] }, "PlatformAdminRoleGrant": { "type": "object", "additionalProperties": false, "required": [ "assignmentId", "role" ], "properties": { "assignmentId": { "type": "string", "minLength": 1, "maxLength": 191 }, "role": { "$ref": "#/components/schemas/PlatformAdminRole" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "AdminPlatformRoleAssignment": { "type": "object", "additionalProperties": false, "required": [ "id", "user", "role", "scope", "reason", "revokeReason", "expiresAt", "revokedAt", "createdAt", "updatedAt", "active", "protected" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "user": { "$ref": "#/components/schemas/AdminPlatformRoleUser" }, "role": { "$ref": "#/components/schemas/PlatformAdminRole" }, "scope": { "$ref": "#/components/schemas/AdminPlatformRoleScope" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "revokeReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" }, "protected": { "type": "boolean" } } }, "AdminPlatformRoleAssignmentListData": { "type": "object", "additionalProperties": false, "required": [ "items", "count", "current" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AdminPlatformRoleAssignment" } }, "count": { "type": "integer", "minimum": 0, "maximum": 100 }, "current": { "$ref": "#/components/schemas/AdminPlatformRoleAssignmentCurrent" } } }, "AdminPlatformRoleAssignmentListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformRoleAssignmentListData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformRoleGrantInput": { "type": "object", "additionalProperties": false, "required": [ "email", "role", "reason" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "role": { "$ref": "#/components/schemas/PlatformAdminRole" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "expiresAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "AdminPlatformRoleGrantData": { "type": "object", "additionalProperties": false, "required": [ "assignment", "revived", "revokedSessions" ], "properties": { "assignment": { "$ref": "#/components/schemas/AdminPlatformRoleAssignment" }, "revived": { "type": "boolean" }, "revokedSessions": { "type": "boolean", "const": true } } }, "AdminPlatformRoleGrantEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformRoleGrantData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformRoleRevokeInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "AdminPlatformRoleRevokeData": { "type": "object", "additionalProperties": false, "required": [ "assignment", "alreadyRevoked", "revokedSessions" ], "properties": { "assignment": { "$ref": "#/components/schemas/AdminPlatformRoleAssignment" }, "alreadyRevoked": { "type": "boolean" }, "revokedSessions": { "type": "boolean" } } }, "AdminPlatformRoleRevokeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformRoleRevokeData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformOperationsCommandInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "AdminPlatformOperationsConsoleData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "permissions", "audit", "security", "quality", "credentials" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-platform-operations-console-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "permissions": { "$ref": "#/components/schemas/AdminPlatformConsolePermissions" }, "audit": { "$ref": "#/components/schemas/AdminPlatformConsoleAudit" }, "security": { "$ref": "#/components/schemas/AdminPlatformSecurityState" }, "quality": { "$ref": "#/components/schemas/AdminPlatformQualityResult" }, "credentials": { "$ref": "#/components/schemas/AdminPlatformCredentialState" } } }, "AdminPlatformOperationsConsoleEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformOperationsConsoleData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformSessionRevokeData": { "type": "object", "additionalProperties": false, "required": [ "sessionId", "unchanged" ], "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 191 }, "revokedAt": { "type": "string", "format": "date-time" }, "unchanged": { "type": "boolean" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "AdminPlatformSessionRevokeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformSessionRevokeData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformQualityReviewData": { "type": "object", "additionalProperties": false, "required": [ "quality", "auditEvent" ], "properties": { "quality": { "$ref": "#/components/schemas/AdminPlatformQualityResult" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "AdminPlatformQualityReviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformQualityReviewData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminPlatformCredentialRotateData": { "type": "object", "additionalProperties": false, "required": [ "credential", "secret", "auditEvent" ], "properties": { "credential": { "$ref": "#/components/schemas/PublicIntegrationCredential" }, "secret": { "type": "string", "pattern": "^vsm_sk_[A-Za-z0-9_-]+$", "minLength": 24, "maxLength": 512, "writeOnly": true }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "AdminPlatformCredentialRotateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminPlatformCredentialRotateData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "ApiMeta": { "type": "object", "additionalProperties": false, "required": [ "requestId", "timestamp" ], "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "ApiErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "VALIDATION_ERROR", "RATE_LIMITED", "PAYLOAD_TOO_LARGE", "ENTITLEMENT_REQUIRED", "EXTERNAL_SERVICE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketQueueConfigurationInput": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "autoActivationEnabled": { "type": "boolean" }, "loadThreshold": { "type": "integer", "minimum": 5, "maximum": 100000 }, "graceTimeoutSeconds": { "type": "integer", "minimum": 60, "maximum": 1800 }, "lotteryDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "maxConcurrentCheckouts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "maxQueueSize": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] } } }, "PublicTicketQueueJoinInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "browserKey" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "browserKey": { "type": "string", "minLength": 16, "maxLength": 200 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "PublicTicketQueueSessionInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "browserKey", "sessionToken" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "browserKey": { "type": "string", "minLength": 16, "maxLength": 200 }, "sessionToken": { "type": "string", "pattern": "^tq_[0-9a-f]{64}$" }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "TicketTransferCreate": { "type": "object", "additionalProperties": false, "required": [ "recipientEmail" ], "properties": { "recipientEmail": { "type": "string", "format": "email", "maxLength": 320 }, "message": { "type": "string", "maxLength": 500 } } }, "TicketTransferSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketId", "direction", "status", "recipientEmailMasked", "senderName", "recipientName", "offering", "ticket", "message", "expiresAt", "acceptedAt", "declinedAt", "revokedAt", "expiredAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "ticketId": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "recipientEmailMasked": { "type": "string" }, "senderName": { "type": "string" }, "recipientName": { "type": "string" }, "offering": { "type": "object", "additionalProperties": true }, "ticket": { "type": "object", "additionalProperties": true }, "message": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "declinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PublicTicketTransfer": { "type": "object", "additionalProperties": false, "required": [ "tenant", "transfer", "ticket" ], "properties": { "tenant": { "type": "object", "additionalProperties": true }, "transfer": { "type": "object", "additionalProperties": true }, "ticket": { "type": "object", "additionalProperties": true } } }, "CustomerAccountErasureStatus": { "type": "object", "additionalProperties": false, "required": [ "requestId", "status", "requestedAt", "scheduledAt", "cancelledAt", "completedAt", "failedAt", "nextAttemptAt", "attempts", "canCancel" ], "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "failed", "completed", "cancelled" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "scheduledAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "nextAttemptAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "integer", "minimum": 0 }, "canCancel": { "type": "boolean" } } }, "CustomerAccountErasureRequest": { "type": "object", "additionalProperties": false, "required": [ "confirmEmail" ], "properties": { "confirmEmail": { "type": "string", "format": "email", "maxLength": 320 }, "reason": { "type": "string", "maxLength": 500 } } }, "CustomerAccountErasureCancel": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 256 } } }, "CustomerNotificationPreferenceUpdate": { "type": "object", "additionalProperties": false, "required": [ "topic", "channel", "enabled" ], "properties": { "topic": { "type": "string", "enum": [ "bookingReminders", "eventUpdates", "accountMessages" ] }, "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "enabled": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 0 } } }, "CustomerNotificationPreferenceUpdateDocument": { "type": "object", "additionalProperties": false, "required": [ "version", "updates" ], "properties": { "version": { "type": "string", "const": "vsm-notification-preferences-v1" }, "updates": { "type": "array", "minItems": 1, "maxItems": 9, "items": { "$ref": "#/components/schemas/CustomerNotificationPreferenceUpdate" } } } }, "CustomerNotificationPreferenceDocument": { "type": "object", "additionalProperties": false, "required": [ "version", "preferences" ], "properties": { "version": { "type": "string", "const": "vsm-notification-preferences-v1" }, "preferences": { "type": "array", "minItems": 9, "maxItems": 9, "items": { "type": "object", "additionalProperties": false, "required": [ "topic", "channel", "enabled", "revision", "updatedAt" ], "properties": { "topic": { "type": "string", "enum": [ "bookingReminders", "eventUpdates", "accountMessages" ] }, "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } } }, "CustomerPushDeviceRegistration": { "type": "object", "additionalProperties": false, "required": [ "version", "installationId", "registrationToken", "platform", "displayName" ], "properties": { "version": { "type": "string", "const": "vsm-push-device-v1" }, "installationId": { "type": "string", "minLength": 16, "maxLength": 256 }, "registrationToken": { "type": "string", "minLength": 16, "maxLength": 4096 }, "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "appVersion": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "CustomerPushDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "platform", "displayName", "appVersion", "status", "registeredAt", "lastSeenAt", "rotatedAt", "revokedAt", "invalidatedAt" ], "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "displayName": { "type": "string" }, "appVersion": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "revoked", "invalid" ] }, "registeredAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "rotatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "invalidatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerNotificationSettings": { "type": "object", "additionalProperties": false, "required": [ "notificationPreferences", "pushDevices" ], "properties": { "notificationPreferences": { "$ref": "#/components/schemas/CustomerNotificationPreferenceDocument" }, "pushDevices": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPushDevice" } } } }, "ConversationAttachmentInput": { "type": "object", "additionalProperties": false, "required": [ "originalName", "mimeType", "contentBase64" ], "properties": { "originalName": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "const": "text/plain" }, "contentBase64": { "type": "string", "minLength": 4, "maxLength": 87384, "pattern": "^[A-Za-z0-9+/]+={0,2}$", "writeOnly": true } } }, "ConversationContextInput": { "type": "object", "additionalProperties": false, "properties": { "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "ConversationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "subject", "bodyText" ], "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 10000 }, "context": { "$ref": "#/components/schemas/ConversationContextInput" }, "support": { "$ref": "#/components/schemas/CustomerSupportCaseCreateInput" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAttachmentInput" }, "maxItems": 3 } } }, "ConversationReplyInput": { "type": "object", "additionalProperties": false, "required": [ "bodyText" ], "properties": { "bodyText": { "type": "string", "minLength": 1, "maxLength": 10000 }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAttachmentInput" }, "maxItems": 3 } } }, "ConversationReadInput": { "type": "object", "additionalProperties": false, "properties": { "messageId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "ConversationCloseInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 } } }, "ConversationAttachment": { "type": "object", "additionalProperties": false, "required": [ "id", "originalName", "mimeType", "sizeBytes", "createdAt", "downloadPath" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "originalName": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "const": "text/plain" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 65536 }, "createdAt": { "type": "string", "format": "date-time" }, "downloadPath": { "type": "string", "minLength": 1, "maxLength": 2048 } } }, "ConversationParticipant": { "type": "object", "additionalProperties": false, "required": [ "id", "role", "displayName" ], "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "customer", "operator" ] }, "displayName": { "type": "string" } } }, "ConversationMessage": { "type": "object", "additionalProperties": false, "required": [ "id", "author", "visibility", "bodyText", "createdAt", "attachments" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "author": { "type": "object", "additionalProperties": false, "required": [ "participantId", "role", "displayName" ], "properties": { "participantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "customer", "operator" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 10000 }, "createdAt": { "type": "string", "format": "date-time" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAttachment" }, "maxItems": 3 } } }, "ConversationThread": { "type": "object", "additionalProperties": false, "required": [ "id", "subject", "status", "revision", "customer", "prospect", "assignee", "context", "supportCase", "lastMessageAt", "lastMessagePreview", "unreadCount", "closedAt", "createdAt", "participants", "messages" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "revision": { "type": "integer", "minimum": 1 }, "customer": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "emailMasked" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMasked": { "type": "string", "minLength": 3, "maxLength": 320 } } }, { "type": "null" } ] }, "prospect": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "emailMasked" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMasked": { "oneOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "type": "null" } ] } } }, { "type": "null" } ] }, "assignee": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "userId", "displayName", "isActor" ], "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 320 }, "isActor": { "type": "boolean" } } }, { "type": "null" } ] }, "context": { "type": "object", "additionalProperties": false, "required": [ "bookingId", "eventId", "ticketOrderId", "supportCaseId" ], "properties": { "bookingId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "eventId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "ticketOrderId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "supportCaseId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } } }, "supportCase": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "caseNumber", "category", "status", "priority", "assignedToUserId", "responseDueAt", "firstResponseAt", "resolvedAt", "revision", "slaState" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "caseNumber": { "type": "string", "minLength": 10, "maxLength": 32 }, "category": { "type": "string", "enum": [ "technical", "billing", "account", "bookings", "events", "tickets", "general" ] }, "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "assignedToUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "responseDueAt": { "type": "string", "format": "date-time" }, "firstResponseAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "resolvedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1 }, "slaState": { "type": "string", "enum": [ "onTrack", "dueSoon", "overdue", "waitingOnCustomer", "resolved" ] } } }, { "type": "null" } ] }, "lastMessageAt": { "type": "string", "format": "date-time" }, "lastMessagePreview": { "type": "string", "minLength": 0, "maxLength": 140 }, "unreadCount": { "type": "integer", "minimum": 0 }, "closedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "participants": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "role", "displayName" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "customer", "operator" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" } } } }, "ConversationList": { "type": "object", "additionalProperties": false, "required": [ "threads", "truncated" ], "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationThread" }, "maxItems": 100 }, "truncated": { "type": "boolean" } } }, "ConversationThreadEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ConversationThreadResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSlot": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "calendarId", "startsAt", "endsAt", "capacity", "reserved", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "calendarId": { "type": "string" }, "seatMapId": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "capacity": { "type": "integer", "minimum": 1 }, "reserved": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BookingSlotEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSlot" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSlotListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSlot" } }, "page": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSlotMaterializeInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "date" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BookingSlotMaterializeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "slots" ], "properties": { "slots": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSlot" } } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "Booking": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "calendarId", "guestName", "partySize", "channel", "status", "paymentStatus", "startsAt", "endsAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "channel": { "type": "string", "enum": [ "web", "phone", "walkIn", "internal" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "paymentStatus": { "type": "string", "enum": [ "notRequired", "pending", "paid", "refunded", "failed" ] }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "type": "string", "format": "date-time" }, "checkedInAt": { "type": "string", "format": "date-time" }, "checkedInByUserId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "OperatorBookingCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "calendarId", "guestName", "partySize", "startsAt", "endsAt" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "paymentStatus": { "type": "string", "enum": [ "notRequired", "pending", "paid", "refunded", "failed" ], "default": "notRequired" }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "channel": { "type": "string", "enum": [ "phone", "walkIn", "internal" ], "default": "internal" } } }, "BookingAttendanceInput": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "BookingAttendanceEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "bookingId", "action", "occurredAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "action": { "type": "string", "enum": [ "checkedIn", "checkInReverted" ] }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 160 }, "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" } } }, "SeatAssignment": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "seatMapId", "source", "status", "seatLabel", "quantity", "assignedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "seatMapId": { "type": "string" }, "seatBlockId": { "type": "string" }, "seatUnitId": { "type": "string" }, "slotId": { "type": "string" }, "scopeKind": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" }, "scopeKey": { "type": "string" }, "offeringId": { "type": "string" }, "eventInstanceId": { "type": "string" }, "bookingId": { "type": "string" }, "ticketId": { "type": "string" }, "sourceHoldId": { "type": "string" }, "source": { "type": "string", "enum": [ "booking", "ticket" ] }, "status": { "type": "string", "enum": [ "active", "released", "cancelled" ] }, "seatLabel": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "assignedAt": { "type": "string", "format": "date-time" }, "releasedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SeatAssignmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatAssignment" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatAssignmentTarget": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "seatUnitId" ], "properties": { "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, { "type": "object", "additionalProperties": false, "required": [ "seatBlockId" ], "properties": { "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 } } } ] }, "SeatAssignmentReassignInput": { "type": "object", "additionalProperties": false, "required": [ "expectedUpdatedAt", "target" ], "properties": { "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "target": { "$ref": "#/components/schemas/SeatAssignmentTarget" } } }, "SeatAssignmentReleaseInput": { "type": "object", "additionalProperties": false, "required": [ "expectedUpdatedAt" ], "properties": { "expectedUpdatedAt": { "type": "string", "format": "date-time" } } }, "SeatAssignmentTargetSnapshot": { "type": "object", "additionalProperties": false, "required": [ "seatLabel", "quantity" ], "properties": { "seatBlockId": { "type": "string" }, "seatUnitId": { "type": "string" }, "seatLabel": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } } }, "SeatAssignmentCommandResult": { "type": "object", "additionalProperties": false, "required": [ "assignment", "auditEventId", "previousTarget", "occupancyDelta" ], "properties": { "assignment": { "$ref": "#/components/schemas/SeatAssignment" }, "auditEventId": { "type": "string" }, "previousTarget": { "$ref": "#/components/schemas/SeatAssignmentTargetSnapshot" }, "occupancyDelta": { "type": "object", "additionalProperties": false, "required": [ "released", "assigned" ], "properties": { "released": { "type": "integer", "minimum": 0 }, "assigned": { "type": "integer", "minimum": 0 } } } } }, "SeatAssignmentCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatAssignmentCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OperatorWalkInInput": { "type": "object", "additionalProperties": false, "required": [ "guestName", "partySize", "seatMapId", "targets" ], "properties": { "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "notes": { "type": "string", "maxLength": 5000 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "targets": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "seatUnitId", "quantity" ], "properties": { "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "const": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "seatBlockId", "quantity" ], "properties": { "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 } } } ] } } } }, "OperatorWalkInResult": { "type": "object", "additionalProperties": false, "required": [ "booking", "assignments", "auditEventId", "replayed", "occupancyDelta" ], "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "assignments": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SeatAssignment" } }, "auditEventId": { "type": "string" }, "replayed": { "type": "boolean" }, "occupancyDelta": { "type": "object", "additionalProperties": false, "required": [ "slotReserved", "assigned" ], "properties": { "slotReserved": { "type": "integer", "minimum": 1 }, "assigned": { "type": "integer", "minimum": 1 } } } } }, "OperatorWalkInEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OperatorWalkInResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventInstanceInput": { "type": "object", "additionalProperties": false, "required": [ "startsAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" }, "cancelled": { "type": "boolean", "default": false } } }, "EventInstance": { "type": "object", "additionalProperties": false, "required": [ "id", "startsAt", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "cancelled": { "type": "boolean" } } }, "EventRecurrenceInput": { "type": "object", "additionalProperties": false, "required": [ "timezone", "startDate", "startTime" ], "properties": { "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "startDate": { "type": "string", "format": "date" }, "endDate": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "endTime": { "oneOf": [ { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "frequency": { "type": "string", "enum": [ "once", "daily", "weekly" ], "default": "once" }, "daysOfWeek": { "type": "array", "maxItems": 7, "uniqueItems": true, "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "count": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "null" } ] }, "excludeDates": { "type": "array", "maxItems": 90, "uniqueItems": true, "items": { "type": "string", "format": "date" } } } }, "EventCreateInput": { "type": "object", "additionalProperties": false, "required": [ "title", "slug" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "organizerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "minLength": 0, "maxLength": 10000 }, "category": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "externalUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "ticketingUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "archived" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "public" }, "language": { "type": "string", "enum": [ "de", "en" ], "default": "de" }, "branding": { "$ref": "#/components/schemas/EventBrandingTheme" }, "imageUrl": { "type": "string", "format": "uri" }, "instances": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EventInstanceInput" } }, "recurrence": { "$ref": "#/components/schemas/EventRecurrenceInput" } } }, "EventUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "organizerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "category": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "tags": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "externalUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "ticketingUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "public" }, "language": { "type": "string", "enum": [ "de", "en" ], "default": "de" }, "branding": { "$ref": "#/components/schemas/EventBrandingTheme" }, "imageUrl": { "type": "string", "format": "uri" }, "instances": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EventInstanceInput" } }, "recurrence": { "$ref": "#/components/schemas/EventRecurrenceInput" } }, "minProperties": 1 }, "Event": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "title", "slug", "status", "language", "instances", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "organizerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "category": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "externalUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "ticketingUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "archived" ] }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ] }, "language": { "type": "string", "enum": [ "de", "en" ] }, "branding": { "type": "object", "additionalProperties": true }, "imageUrl": { "type": "string", "format": "uri" }, "instances": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EventInstance" } }, "publishedAt": { "type": "string", "format": "date-time" } } }, "EventEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Event" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOrganizer": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "name", "email", "phone", "websiteUrl", "notes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 220 }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 64 }, { "type": "null" } ] }, "websiteUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "notes": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] } } }, "EventOrganizerInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 220 }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "websiteUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "notes": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, "ArtistExternalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri" }, "spotify": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" }, "facebook": { "type": "string", "format": "uri" }, "youtube": { "type": "string", "format": "uri" } } }, "ArtistRelease": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string", "maxLength": 80 } } }, "Artist": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "name", "slug", "bio", "genres", "imageUrl", "thumbnailUrl", "countryCode", "externalLinks", "recentReleases", "musicBrainzId", "spotifyId", "syncStatus", "lastSyncedAt", "syncError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120 }, "bio": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "genres": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 64 } }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "thumbnailUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "externalLinks": { "$ref": "#/components/schemas/ArtistExternalLinks" }, "recentReleases": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ArtistRelease" } }, "musicBrainzId": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "spotifyId": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "syncStatus": { "type": "string", "enum": [ "pending", "synced", "failed", "manual" ] }, "lastSyncedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "syncError": { "oneOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ArtistInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120 }, "bio": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "genres": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 64 } }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "thumbnailUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "externalLinks": { "$ref": "#/components/schemas/ArtistExternalLinks" }, "recentReleases": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ArtistRelease" } }, "musicBrainzId": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "spotifyId": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } } }, "EventLineupEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "eventId", "artistId", "sortOrder", "role", "setTime", "setDurationMinutes", "stageName", "displayName", "artist", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "eventId": { "type": "string" }, "artistId": { "type": "string" }, "sortOrder": { "type": "integer", "minimum": 0 }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "oneOf": [ { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "null" } ] }, "setDurationMinutes": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1440 }, { "type": "null" } ] }, "stageName": { "oneOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "displayName": { "oneOf": [ { "type": "string", "maxLength": 220 }, { "type": "null" } ] }, "artist": { "$ref": "#/components/schemas/Artist" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventLineup": { "type": "object", "additionalProperties": false, "required": [ "eventId", "organizer", "artists" ], "properties": { "eventId": { "type": "string" }, "organizer": { "oneOf": [ { "$ref": "#/components/schemas/EventOrganizer" }, { "type": "null" } ] }, "artists": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/EventLineupEntry" } } } }, "EventLineupReplaceInput": { "type": "object", "additionalProperties": false, "required": [ "organizerId", "artists" ], "properties": { "organizerId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "artists": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "artistId", "role" ], "properties": { "artistId": { "type": "string" }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "oneOf": [ { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "null" } ] }, "setDurationMinutes": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1440 }, { "type": "null" } ] }, "stageName": { "oneOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "displayName": { "oneOf": [ { "type": "string", "maxLength": 220 }, { "type": "null" } ] } } } } } }, "EventLineupEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventLineup" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOrganizerEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOrganizer" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOrganizerListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOrganizerListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "ArtistEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Artist" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "ArtistListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "artists" ], "properties": { "artists": { "type": "array", "items": { "$ref": "#/components/schemas/Artist" } } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventSecretLink": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "eventId", "slug", "status", "last4", "expiresAt", "maxUses", "usageCount", "createdByUserId", "createdAt", "updatedAt", "revokedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "eventId": { "type": "string" }, "slug": { "type": "string", "minLength": 16, "maxLength": 64 }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "last4": { "type": "string", "minLength": 4, "maxLength": 4 }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "maxUses": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 500 }, { "type": "null" } ] }, "usageCount": { "type": "integer", "minimum": 0 }, "createdByUserId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "EventSecretLinkCreateInput": { "type": "object", "additionalProperties": false, "properties": { "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "maxUses": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 500 }, { "type": "null" } ] }, "replaceExisting": { "type": "boolean", "default": true } } }, "EventSecretLinkListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/EventSecretLink" } } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventSecretLinkCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "link", "token", "url" ], "properties": { "link": { "$ref": "#/components/schemas/EventSecretLink" }, "token": { "type": "string", "minLength": 32, "writeOnly": true }, "url": { "type": "string", "format": "uri", "writeOnly": true } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatOccupancyScopeKind": { "type": "string", "enum": [ "bookingSlot", "eventInstance", "ticketOffering", "legacyGlobal" ] }, "SeatmapAnalyticsScope": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "all", "explicit" ] }, "scopeKind": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" }, "scopeKey": { "type": "string" } } }, "SeatmapAnalyticsOverview": { "type": "object", "additionalProperties": false, "required": [ "capacity", "assigned", "activeHolds", "occupancyPercent", "assignmentQuantity", "holdGroups", "conversionRate", "trend", "trendPoints" ], "properties": { "capacity": { "type": "integer", "minimum": 0 }, "assigned": { "type": "integer", "minimum": 0 }, "activeHolds": { "type": "integer", "minimum": 0 }, "occupancyPercent": { "type": "number", "minimum": 0 }, "assignmentQuantity": { "type": "integer", "minimum": 0 }, "holdGroups": { "type": "integer", "minimum": 0 }, "conversionRate": { "type": "number", "minimum": 0, "maximum": 100 }, "trend": { "type": "string", "enum": [ "up", "down", "stable" ] }, "trendPoints": { "type": "number", "minimum": 0 } } }, "SeatmapAnalyticsFunnel": { "type": "object", "additionalProperties": false, "required": [ "created", "converted", "expired", "releasedUnconverted", "conversionRate", "averageDurationMinutes" ], "properties": { "created": { "type": "integer", "minimum": 0 }, "converted": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "releasedUnconverted": { "type": "integer", "minimum": 0 }, "conversionRate": { "type": "number", "minimum": 0, "maximum": 100 }, "averageDurationMinutes": { "type": "integer", "minimum": 0 } } }, "SeatmapAnalyticsTimelinePoint": { "type": "object", "additionalProperties": false, "required": [ "date", "assignments", "holdGroups", "assignedAtEnd", "occupancyPercent" ], "properties": { "date": { "type": "string", "format": "date" }, "assignments": { "type": "integer", "minimum": 0 }, "holdGroups": { "type": "integer", "minimum": 0 }, "assignedAtEnd": { "type": "integer", "minimum": 0 }, "occupancyPercent": { "type": "number", "minimum": 0 } } }, "SeatmapAnalyticsSource": { "type": "object", "additionalProperties": false, "required": [ "source", "quantity", "percent" ], "properties": { "source": { "type": "string", "enum": [ "web", "phone", "walkIn", "internal", "ticket" ] }, "quantity": { "type": "integer", "minimum": 0 }, "percent": { "type": "number", "minimum": 0, "maximum": 100 } } }, "SeatmapAnalyticsPopularTarget": { "type": "object", "additionalProperties": false, "required": [ "rank", "targetKind", "targetId", "label", "assignmentCount", "quantity" ], "properties": { "rank": { "type": "integer", "minimum": 1 }, "targetKind": { "type": "string", "enum": [ "seat", "block" ] }, "targetId": { "type": "string" }, "label": { "type": "string" }, "blockLabel": { "type": "string" }, "assignmentCount": { "type": "integer", "minimum": 0 }, "quantity": { "type": "integer", "minimum": 0 } } }, "SeatmapAnalyticsDataQuality": { "type": "object", "additionalProperties": false, "required": [ "excludedLegacyHolds", "excludedLegacyAssignments", "capacityBasis" ], "properties": { "excludedLegacyHolds": { "type": "integer", "minimum": 0 }, "excludedLegacyAssignments": { "type": "integer", "minimum": 0 }, "capacityBasis": { "type": "string", "enum": [ "currentLayout" ] } } }, "SeatmapAnalyticsReadModel": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "tenantId", "seatMapId", "seatMapName", "period", "scope", "overview", "funnel", "timeline", "sources", "popularTargets", "dataQuality" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string" }, "seatMapId": { "type": "string" }, "seatMapName": { "type": "string" }, "period": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "days" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "days": { "type": "integer", "minimum": 1, "maximum": 90 } } }, "scope": { "$ref": "#/components/schemas/SeatmapAnalyticsScope" }, "overview": { "$ref": "#/components/schemas/SeatmapAnalyticsOverview" }, "funnel": { "$ref": "#/components/schemas/SeatmapAnalyticsFunnel" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapAnalyticsTimelinePoint" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapAnalyticsSource" } }, "popularTargets": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapAnalyticsPopularTarget" }, "maxItems": 10 }, "dataQuality": { "$ref": "#/components/schemas/SeatmapAnalyticsDataQuality" } } }, "SeatmapAnalyticsEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatmapAnalyticsReadModel" }, "meta": { "type": "object" } } }, "SeatmapOccupancyQuantitySummary": { "type": "object", "additionalProperties": false, "required": [ "activeHolds", "assignments", "reserved" ], "properties": { "activeHolds": { "type": "integer", "minimum": 0 }, "assignments": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 } } }, "SeatmapOccupancyMetrics": { "type": "object", "additionalProperties": false, "required": [ "activeHolds", "assignments", "reserved", "conflicts" ], "properties": { "activeHolds": { "type": "integer", "minimum": 0 }, "assignments": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "conflicts": { "type": "integer", "minimum": 0 } } }, "SeatmapOccupancyScopeSource": { "type": "object", "additionalProperties": false, "properties": { "slotId": { "type": "string" }, "eventInstanceId": { "type": "string" }, "offeringId": { "type": "string" } } }, "SeatmapOccupancyScopeDisplay": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" } } }, "SeatmapOccupancyScopeDescriptor": { "type": "object", "additionalProperties": false, "required": [ "scopeKind", "scopeKey", "legacy", "display", "source", "allocationSources", "allocationSummary" ], "properties": { "scopeKind": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" }, "scopeKey": { "type": "string" }, "legacy": { "type": "boolean" }, "display": { "$ref": "#/components/schemas/SeatmapOccupancyScopeDisplay" }, "source": { "$ref": "#/components/schemas/SeatmapOccupancyScopeSource" }, "allocationSources": { "type": "array", "items": { "type": "string", "enum": [ "booking", "ticket" ] }, "uniqueItems": true }, "allocationSummary": { "$ref": "#/components/schemas/SeatmapOccupancyQuantitySummary" } } }, "SeatmapOccupancyScopeSelection": { "type": "object", "additionalProperties": false, "required": [ "mode", "selectionRequired", "selectedScope", "includesLegacyGlobalBlockers" ], "properties": { "mode": { "type": "string", "enum": [ "explicit", "singleAvailable", "none", "ambiguous" ] }, "selectionRequired": { "type": "boolean" }, "selectedScope": { "oneOf": [ { "$ref": "#/components/schemas/SeatmapOccupancyScopeDescriptor" }, { "type": "null" } ] }, "includesLegacyGlobalBlockers": { "type": "boolean" } } }, "SeatmapOccupancyRow": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "source", "customerLabel", "timeLabel", "seatLabel", "blockLabel", "scopeKind", "scopeKey", "scopeRelation", "quantity", "status", "createdAt" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "hold", "assignment" ] }, "source": { "type": "string", "enum": [ "booking", "ticket" ] }, "customerLabel": { "type": "string" }, "timeLabel": { "type": "string" }, "seatLabel": { "type": "string" }, "blockLabel": { "type": "string" }, "scopeKind": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" }, "scopeKey": { "type": "string" }, "scopeRelation": { "type": "string", "enum": [ "selected", "legacyGlobalBlocker" ] }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "Reserviert", "Gebucht", "Konflikt" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SeatmapOccupancyTarget": { "type": "object", "additionalProperties": false, "required": [ "targetKind", "targetId", "label", "capacity", "direct", "related", "effectiveReserved", "remainingQuantity", "status" ], "properties": { "targetKind": { "type": "string", "enum": [ "block", "seat" ] }, "targetId": { "type": "string" }, "label": { "type": "string" }, "blockId": { "type": "string" }, "capacity": { "type": "integer", "minimum": 0 }, "direct": { "$ref": "#/components/schemas/SeatmapOccupancyQuantitySummary" }, "related": { "$ref": "#/components/schemas/SeatmapOccupancyQuantitySummary" }, "effectiveReserved": { "type": "integer", "minimum": 0 }, "remainingQuantity": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "available", "held", "booked", "mixed", "conflict" ] } } }, "SeatmapOccupancyReadModel": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "tenantId", "seatMapId", "scopeSelection", "availableScopes", "metrics", "targets", "rows" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string" }, "seatMapId": { "type": "string" }, "scopeSelection": { "$ref": "#/components/schemas/SeatmapOccupancyScopeSelection" }, "availableScopes": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapOccupancyScopeDescriptor" } }, "metrics": { "$ref": "#/components/schemas/SeatmapOccupancyMetrics" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapOccupancyTarget" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/SeatmapOccupancyRow" } } } }, "SeatmapOccupancyEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatmapOccupancyReadModel" }, "meta": { "type": "object" } } }, "SeatMapCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "name" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "maxLength": 5000 }, "layout": { "$ref": "#/components/schemas/SeatMapLayoutDocument" } } }, "SeatMapUpdateInput": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "maxLength": 5000 } } }, "SeatMapLayoutDocument": { "type": "object", "additionalProperties": false, "description": "Strict durable vsm-seatmap-layout-v1 document. Unknown keys, transient statuses, duplicate/orphan identities, invalid room/background references, out-of-bounds geometry, and capacity mismatches are rejected with path-specific issues.", "required": [ "schemaVersion", "templateId", "holdTtlSeconds", "canvas", "blocks", "seats", "blockCapacities" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-seatmap-layout-v1" }, "templateId": { "type": "string", "enum": [ "small-room", "restaurant", "theater", "free-zone" ] }, "holdTtlSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "canvas": { "type": "object" }, "blocks": { "type": "array", "maxItems": 1000, "items": { "type": "object" } }, "seats": { "type": "array", "maxItems": 10000, "items": { "type": "object" } }, "blockCapacities": { "type": "object" }, "rooms": { "type": "array", "maxItems": 50, "items": { "type": "object" } } } }, "SeatPricingDocument": { "type": "object", "additionalProperties": false, "description": "Strict canonical vsm-seat-pricing-v1 document for every new TicketOffering write. Ticket type resolution precedence is seats[targetId], blocks[parentBlockId], then defaultTicketTypeId. Legacy rules/seatBlocks/seatUnits aliases are read-migration inputs only and are rejected on new writes.", "required": [ "schema", "required", "blocks", "seats" ], "properties": { "schema": { "type": "string", "const": "vsm-seat-pricing-v1" }, "required": { "type": "boolean" }, "defaultTicketTypeId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$" }, "blocks": { "type": "object", "maxProperties": 10000, "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$" } }, "seats": { "type": "object", "maxProperties": 10000, "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$" } } } }, "TicketTypeInput": { "type": "object", "additionalProperties": false, "required": [ "name", "priceAmount" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "priceAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "vatRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "inventoryLimit": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "maxPerOrder": { "type": "integer", "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "TicketOfferingCreateInput": { "type": "object", "additionalProperties": false, "required": [ "title", "ticketTypes" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "description": { "type": "string", "minLength": 0, "maxLength": 10000 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ], "default": "draft" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "saleStartsAt": { "type": "string", "format": "date-time" }, "saleEndsAt": { "type": "string", "format": "date-time" }, "totalLimit": { "type": "integer", "minimum": 0 }, "maxPerOrder": { "type": "integer", "minimum": 1, "maximum": 1000 }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 1000 }, "seatPricing": { "$ref": "#/components/schemas/SeatPricingDocument" }, "ticketTypes": { "type": "array", "items": { "$ref": "#/components/schemas/TicketTypeInput" }, "maxItems": 100, "minItems": 1 } } }, "TicketOfferingUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "eventId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "eventInstanceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "seatMapId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "saleStartsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "saleEndsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "totalLimit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "maxPerOrder": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 5000 }, "seatPricing": { "oneOf": [ { "$ref": "#/components/schemas/SeatPricingDocument" }, { "type": "null" } ] }, "ticketTypes": { "type": "array", "items": { "$ref": "#/components/schemas/TicketTypeInput" }, "maxItems": 100, "minItems": 1 } }, "minProperties": 1 }, "TicketInventoryAdjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "scope", "reason", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "type": "string", "enum": [ "offering", "ticketType" ] }, "previousLimit": { "type": "integer", "minimum": 0 }, "nextLimit": { "type": "integer", "minimum": 0 }, "delta": { "type": "integer" }, "reason": { "type": "string", "enum": [ "initial", "manual", "system" ] }, "note": { "type": "string", "minLength": 0, "maxLength": 2000 }, "createdByUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" } } }, "TicketInventoryAdjustmentList": { "type": "object", "additionalProperties": false, "required": [ "items", "limit", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketInventoryAdjustment" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" } } }, "TicketScanOutcome": { "type": "string", "enum": [ "accepted", "alreadyRedeemed", "invalidCode", "invalidStatus", "offlinePackageExpired", "offlinePackageRevoked", "wrongEvent" ] }, "TicketScanTicketSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketReference", "status", "ticketTypeName", "offeringTitle", "buyerDisplay" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketReference": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Masked, non-redeemable display reference" }, "status": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "ticketTypeName": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringTitle": { "type": "string", "minLength": 1, "maxLength": 220 }, "buyerDisplay": { "type": "string", "minLength": 1, "maxLength": 320 }, "noShowAt": { "type": "string", "format": "date-time" }, "checkedInAt": { "type": "string", "format": "date-time" } } }, "TicketScanRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "clientEventId", "origin", "outcome", "occurredAt", "receivedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "clientEventId": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "live", "offline" ] }, "outcome": { "$ref": "#/components/schemas/TicketScanOutcome" }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "ticketId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offlinePackageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticket": { "$ref": "#/components/schemas/TicketScanTicketSummary" } } }, "TicketLiveScanInput": { "type": "object", "additionalProperties": false, "required": [ "clientEventId", "occurredAt", "code" ], "properties": { "clientEventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketOfflinePackageCreateInput": { "type": "object", "additionalProperties": false, "required": [ "offeringId", "deviceId" ], "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expiresInMinutes": { "type": "integer", "minimum": 15, "maximum": 720, "default": 240 } } }, "TicketOfflinePackageItem": { "type": "object", "additionalProperties": false, "required": [ "ticketId", "codeDigests", "status", "ticketTypeName", "offeringTitle", "buyerDisplay" ], "properties": { "ticketId": { "type": "string", "minLength": 1, "maxLength": 160 }, "codeDigests": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "minItems": 2, "maxItems": 2 }, "status": { "type": "string", "enum": [ "valid", "redeemed" ] }, "ticketTypeName": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringTitle": { "type": "string", "minLength": 1, "maxLength": 220 }, "buyerDisplay": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "TicketOfflinePackage": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "deviceId", "salt", "createdAt", "expiresAt", "ticketCount", "items" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "salt": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "ticketCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOfflinePackageItem" }, "maxItems": 5000 } } }, "TicketOfflineSyncInput": { "type": "object", "additionalProperties": false, "required": [ "packageId", "deviceId", "entries" ], "properties": { "packageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOfflineScanEntry" }, "minItems": 1, "maxItems": 200 } } }, "OfflineDeviceCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "name" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 } } }, "OfflineCreditReservationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "eventId", "customerId", "amountMinor" ], "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 191 }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "expiresInMinutes": { "type": "integer", "minimum": 15, "maximum": 720, "default": 240 } } }, "OfflineOperationEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/OfflineTicketScanEnvelope" }, { "$ref": "#/components/schemas/OfflineCouponRedeemEnvelope" }, { "$ref": "#/components/schemas/OfflineEventCreditChargeEnvelope" } ], "discriminator": { "propertyName": "kind" } }, "OfflineOperationsSyncInput": { "type": "object", "additionalProperties": false, "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OfflineOperationEnvelope" }, "minItems": 1, "maxItems": 200 } } }, "StripeConnectAccountInput": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "default": "DE" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$", "default": "EUR" }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "businessUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "productDescription": { "type": "string", "minLength": 8, "maxLength": 5000 } } }, "StripeConnectOnboardingInput": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "default": "DE" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$", "default": "EUR" }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "businessUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "productDescription": { "type": "string", "minLength": 8, "maxLength": 5000 }, "refreshUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "returnUrl": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "StripeConnectStatus": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "status", "transfersEnabled", "payoutsEnabled", "detailsSubmitted", "livemode", "requirementsDue", "futureRequirementsDue", "onboardingComplete", "dashboard", "capabilityStatus" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "none", "pending", "restricted", "active" ] }, "transfersEnabled": { "type": "boolean" }, "payoutsEnabled": { "type": "boolean" }, "detailsSubmitted": { "type": "boolean" }, "livemode": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" }, "requirementsDue": { "type": "integer", "minimum": 0 }, "futureRequirementsDue": { "type": "integer", "minimum": 0 }, "onboardingComplete": { "type": "boolean" }, "dashboard": { "type": "string", "enum": [ "express", "full", "none", "unknown" ] }, "capabilityStatus": { "$ref": "#/components/schemas/StripeConnectCapabilityStatus" } } }, "StripeConnectStatusEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StripeConnectStatus" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "StripeConnectAccountEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StripeConnectAccountResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "StripeConnectOnboardingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/StripeConnectOnboardingResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthTenantCreateInput": { "type": "object", "additionalProperties": false, "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "plan": { "type": "string", "const": "base", "default": "base" }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ], "default": "de" }, "defaultTimezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" }, "branding": { "type": "object", "additionalProperties": true } } }, "AuthRegisterInput": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "password": { "type": "string", "minLength": 12, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenant": { "$ref": "#/components/schemas/AuthTenantCreateInput" } } }, "AuthLoginInput": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "password": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "AuthMagicLinkInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "redirectUrl": { "type": "string", "format": "uri" } } }, "AuthTokenInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 512 } } }, "AuthMfaCodeInput": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 64 } } }, "AuthMfaChallengeInput": { "type": "object", "additionalProperties": false, "required": [ "challengeToken", "code" ], "properties": { "challengeToken": { "type": "string", "minLength": 16, "maxLength": 512 }, "code": { "type": "string", "minLength": 6, "maxLength": 64 } } }, "AuthSession": { "type": "object", "additionalProperties": false, "required": [ "userId", "email", "roles", "authMode" ], "properties": { "userId": { "type": "string" }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "displayName": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "platformAdmin", "owner", "manager", "staff", "customer" ] }, "minItems": 1, "uniqueItems": true }, "authMode": { "type": "string", "enum": [ "placeholder", "session", "apiKey" ] }, "apiKeyCredentialId": { "type": "string" }, "apiKeyScopes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } }, "AuthTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "createdAt", "updatedAt", "slug", "name", "plan", "defaultLocale", "defaultTimezone" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "slug": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ] }, "defaultTimezone": { "type": "string" }, "branding": { "type": "object", "additionalProperties": true }, "stripeConnectAccountId": { "type": "string" }, "stripeConnectStatus": { "type": "string", "enum": [ "none", "pending", "restricted", "active" ] }, "stripeConnectTransfersEnabled": { "type": "boolean" }, "stripeConnectPayoutsEnabled": { "type": "boolean" }, "stripeConnectDetailsSubmitted": { "type": "boolean" }, "stripeConnectLivemode": { "type": "boolean" }, "stripeConnectUpdatedAt": { "type": "string", "format": "date-time" } } }, "AuthTenantMember": { "type": "object", "additionalProperties": false, "required": [ "id", "createdAt", "updatedAt", "tenantId", "email", "role" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string" }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "displayName": { "type": "string" }, "role": { "type": "string", "enum": [ "platformAdmin", "owner", "manager", "staff", "customer" ] }, "invitedAt": { "type": "string", "format": "date-time" }, "joinedAt": { "type": "string", "format": "date-time" } } }, "AuthEntitlement": { "type": "object", "additionalProperties": false, "required": [ "feature", "source" ], "properties": { "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline" ] }, "source": { "type": "string", "enum": [ "plan", "addOn", "override" ] } } }, "AuthTenantContext": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "role", "plan", "addOns", "entitlements" ], "properties": { "tenantId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string", "enum": [ "platformAdmin", "owner", "manager", "staff", "customer" ] }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "addOns": { "type": "array", "items": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "uniqueItems": true }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEntitlement" } } } }, "AuthIssuedSessionData": { "type": "object", "additionalProperties": false, "required": [ "session", "csrfToken", "expiresAt" ], "properties": { "session": { "$ref": "#/components/schemas/AuthSession" }, "csrfToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "redirectUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } } }, "AuthRegisterData": { "type": "object", "additionalProperties": false, "required": [ "session", "tenant", "ownerMember", "csrfToken", "expiresAt" ], "properties": { "session": { "$ref": "#/components/schemas/AuthSession" }, "tenant": { "anyOf": [ { "$ref": "#/components/schemas/AuthTenant" }, { "type": "null" } ] }, "ownerMember": { "anyOf": [ { "$ref": "#/components/schemas/AuthTenantMember" }, { "type": "null" } ] }, "csrfToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "AuthMfaChallengeData": { "type": "object", "additionalProperties": false, "required": [ "mfaRequired", "challengeToken", "expiresAt", "methods" ], "properties": { "mfaRequired": { "type": "boolean", "enum": [ true ] }, "challengeToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "recoveryCode" ] }, "minItems": 2, "maxItems": 2, "uniqueItems": true }, "redirectUrl": { "type": "string", "format": "uri" } } }, "AuthMagicLinkData": { "type": "object", "additionalProperties": false, "required": [ "accepted", "email", "redirectUrl" ], "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "redirectUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "developmentToken": { "type": "string" } } }, "AuthInvite": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "email", "role", "expiresAt", "consumedAt" ], "properties": { "tenantId": { "type": "string" }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "role": { "type": "string", "enum": [ "platformAdmin", "owner", "manager", "staff", "customer" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "consumedAt": { "type": "string", "format": "date-time" } } }, "AuthInviteAcceptData": { "type": "object", "additionalProperties": false, "required": [ "invite", "tenant", "member" ], "properties": { "invite": { "$ref": "#/components/schemas/AuthInvite" }, "tenant": { "$ref": "#/components/schemas/AuthTenant" }, "member": { "$ref": "#/components/schemas/AuthTenantMember" } } }, "AuthLogoutData": { "type": "object", "additionalProperties": false, "required": [ "loggedOut" ], "properties": { "loggedOut": { "type": "boolean", "enum": [ true ] } } }, "AuthLogoutAllData": { "type": "object", "additionalProperties": false, "required": [ "loggedOut", "revokedCount" ], "properties": { "loggedOut": { "type": "boolean", "enum": [ true ] }, "revokedCount": { "type": "integer", "minimum": 0 } } }, "AuthCurrentSessionData": { "type": "object", "additionalProperties": false, "required": [ "session", "tenant", "csrfToken", "expiresAt" ], "properties": { "session": { "anyOf": [ { "$ref": "#/components/schemas/AuthSession" }, { "type": "null" } ] }, "tenant": { "anyOf": [ { "$ref": "#/components/schemas/AuthTenantContext" }, { "type": "null" } ] }, "csrfToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "AuthSessionInventoryItem": { "type": "object", "additionalProperties": false, "required": [ "id", "current", "userAgent", "ipAddress", "deviceLabel", "createdAt", "lastSeenAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "current": { "type": "boolean" }, "userAgent": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "ipAddress": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "deviceLabel": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "AuthSessionInventoryData": { "type": "object", "additionalProperties": false, "required": [ "items", "count" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthSessionInventoryItem" }, "maxItems": 100 }, "count": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "AuthSessionRevocationData": { "type": "object", "additionalProperties": false, "required": [ "revoked", "sessionId", "current" ], "properties": { "revoked": { "type": "boolean", "enum": [ true ] }, "sessionId": { "type": "string" }, "current": { "type": "boolean" } } }, "AuthMfaStatusData": { "type": "object", "additionalProperties": false, "required": [ "enabled", "enabledAt", "recoveryCodesRemaining", "setupPending" ], "properties": { "enabled": { "type": "boolean" }, "enabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recoveryCodesRemaining": { "type": "integer", "minimum": 0, "maximum": 10 }, "setupPending": { "type": "boolean" } } }, "AuthMfaSetupData": { "type": "object", "additionalProperties": false, "required": [ "secret", "otpauthUri" ], "properties": { "secret": { "type": "string", "pattern": "^[A-Z2-7]{32}$" }, "otpauthUri": { "type": "string", "format": "uri" } } }, "AuthMfaConfirmData": { "type": "object", "additionalProperties": false, "required": [ "enabled", "enabledAt", "recoveryCodes", "revokedOtherSessions" ], "properties": { "enabled": { "type": "boolean", "enum": [ true ] }, "enabledAt": { "type": "string", "format": "date-time" }, "recoveryCodes": { "type": "array", "items": { "type": "string" }, "minItems": 10, "maxItems": 10, "uniqueItems": true }, "revokedOtherSessions": { "type": "integer", "minimum": 0 } } }, "AuthMfaDisableData": { "type": "object", "additionalProperties": false, "required": [ "disabled", "revokedOtherSessions" ], "properties": { "disabled": { "type": "boolean", "enum": [ true ] }, "revokedOtherSessions": { "type": "integer", "minimum": 0 } } }, "AuthRegisterEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthRegisterData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthLoginEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AuthIssuedSessionData" }, { "$ref": "#/components/schemas/AuthMfaChallengeData" } ] }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMagicLinkEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMagicLinkData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMagicLinkConsumeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AuthIssuedSessionData" }, { "$ref": "#/components/schemas/AuthMfaChallengeData" } ] }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthInviteAcceptEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthInviteAcceptData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthLogoutEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthLogoutData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthLogoutAllEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthLogoutAllData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthCurrentSessionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthCurrentSessionData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthSessionInventoryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthSessionInventoryData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthSessionRevocationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthSessionRevocationData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaStatusEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMfaStatusData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaSetupEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMfaSetupData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaConfirmEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMfaConfirmData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaChallengeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthIssuedSessionData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaDisableEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMfaDisableData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthSessionAuditItem": { "type": "object", "additionalProperties": false, "required": [ "id", "event", "sessionId", "deviceLabel", "createdAt", "metadata" ], "properties": { "id": { "type": "string" }, "event": { "type": "string", "enum": [ "sessionCreated", "sessionRevoked", "sessionRevokedAll", "newDevice", "newDeviceNotificationQueued", "mfaEnabled", "mfaDisabled", "mfaRecoveryCodesRotated", "mfaRecoveryCodeUsed", "oauthLogin", "oauthLinkRequested", "oauthLinked", "oauthLinkRejected", "oauthUnlinked", "oauthConflict" ] }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceLabel": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] } } }, "AuthSessionAuditData": { "type": "object", "additionalProperties": false, "required": [ "items", "count" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthSessionAuditItem" }, "maxItems": 100 }, "count": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "AuthMfaRecoveryRotationData": { "type": "object", "additionalProperties": false, "required": [ "recoveryCodes", "recoveryCodesRemaining", "revokedOtherSessions" ], "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" }, "minItems": 10, "maxItems": 10, "uniqueItems": true }, "recoveryCodesRemaining": { "type": "integer", "minimum": 10, "maximum": 10 }, "revokedOtherSessions": { "type": "integer", "minimum": 0 } } }, "AuthSessionAuditEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthSessionAuditData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthMfaRecoveryRotationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthMfaRecoveryRotationData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthTenantSelectionInput": { "type": "object", "additionalProperties": false, "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "AuthTenantSelectionData": { "type": "object", "additionalProperties": false, "required": [ "tenant", "csrfToken" ], "properties": { "tenant": { "$ref": "#/components/schemas/AuthTenantContext" }, "csrfToken": { "type": "string" } } }, "AuthTenantSelectionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthTenantSelectionData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CursorPageInfo": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "SeatMap": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "name", "status", "version", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "maxLength": 5000 }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "layout": { "$ref": "#/components/schemas/SeatMapLayoutDocument" }, "version": { "type": "integer", "minimum": 1 }, "isDefault": { "type": "boolean" }, "publishedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SeatMapEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatMap" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatMapPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SeatMap" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "SeatMapPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatMapPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatMapDuplicateInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 } } }, "SeatMapDraftVersionResult": { "type": "object", "additionalProperties": false, "required": [ "source", "draft", "versioning" ], "properties": { "source": { "$ref": "#/components/schemas/SeatMap" }, "draft": { "$ref": "#/components/schemas/SeatMap" }, "versioning": { "type": "object", "additionalProperties": false, "required": [ "nextVersion", "reason" ], "properties": { "nextVersion": { "type": "integer", "minimum": 2 }, "reason": { "type": "string", "enum": [ "published_clone", "manual_clone" ] } } } } }, "SeatMapDraftVersionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatMapDraftVersionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatMapDuplicateResult": { "type": "object", "additionalProperties": false, "required": [ "source", "duplicate", "duplication" ], "properties": { "source": { "$ref": "#/components/schemas/SeatMap" }, "duplicate": { "$ref": "#/components/schemas/SeatMap" }, "duplication": { "type": "object", "additionalProperties": false, "required": [ "independent", "copiedLayout" ], "properties": { "independent": { "type": "boolean", "const": true }, "copiedLayout": { "type": "boolean" } } } } }, "SeatMapDuplicateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatMapDuplicateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatMapDeletionResult": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } }, "SeatMapDeletionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatMapDeletionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatHold": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "seatMapId", "source", "status", "token", "expiresAt", "quantity", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scopeKind": { "$ref": "#/components/schemas/SeatOccupancyScopeKind" }, "scopeKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "enum": [ "booking", "ticket" ] }, "status": { "type": "string", "enum": [ "active", "released", "expired" ] }, "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "expiresAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "releasedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SeatHoldDecision": { "type": "object", "additionalProperties": false, "required": [ "ok", "reason", "blockingHoldIds", "heldQuantity", "projectedQuantity", "capacity" ], "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "seatAvailable", "blockCapacityAvailable", "invalidTarget", "invalidQuantity", "invalidTtl", "seatAlreadyHeld", "blockCapacityExceeded" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "blockingHoldIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "heldQuantity": { "type": "integer", "minimum": 0 }, "projectedQuantity": { "type": "integer" }, "capacity": { "type": "integer" } } }, "SeatAssignmentDecision": { "type": "object", "additionalProperties": false, "required": [ "ok", "reason", "blockingAssignmentIds", "assignedQuantity", "projectedQuantity", "capacity" ], "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "seatAssignable", "blockCapacityAssignable", "invalidTarget", "invalidQuantity", "seatAlreadyAssigned", "blockCapacityExceeded", "ticketAlreadyAssigned" ] }, "blockingAssignmentIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "projectedQuantity": { "type": "integer" }, "capacity": { "type": "integer" } } }, "SeatHoldCreateInput": { "type": "object", "additionalProperties": true, "required": [ "seatMapId", "source", "expiresAt" ], "properties": { "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "enum": [ "booking", "ticket" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "token": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "SeatHoldWorkflowResult": { "type": "object", "additionalProperties": false, "required": [ "hold", "decision", "renewed", "expired" ], "properties": { "hold": { "$ref": "#/components/schemas/SeatHold" }, "decision": { "$ref": "#/components/schemas/SeatHoldDecision" }, "renewed": { "type": "boolean" }, "expired": { "type": "integer", "minimum": 0 } } }, "SeatHoldWorkflowEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatHoldWorkflowResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatHoldAssignmentInput": { "type": "object", "additionalProperties": true, "properties": { "holdId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatLabel": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "SeatHoldAssignmentResult": { "type": "object", "additionalProperties": false, "required": [ "assignment", "hold", "decision" ], "properties": { "assignment": { "$ref": "#/components/schemas/SeatAssignment" }, "hold": { "$ref": "#/components/schemas/SeatHold" }, "decision": { "$ref": "#/components/schemas/SeatAssignmentDecision" } } }, "SeatHoldAssignmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatHoldAssignmentResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatHoldReleaseResult": { "type": "object", "additionalProperties": false, "required": [ "released", "holds", "changed" ], "properties": { "released": { "$ref": "#/components/schemas/SeatHold" }, "holds": { "type": "array", "items": { "$ref": "#/components/schemas/SeatHold" } }, "changed": { "type": "integer", "minimum": 0 } } }, "SeatHoldReleaseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatHoldReleaseResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SeatAssignmentPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SeatAssignment" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "SeatAssignmentPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SeatAssignmentPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicEventSecretAccessInput": { "type": "object", "additionalProperties": false, "required": [ "slug", "key" ], "properties": { "slug": { "type": "string", "minLength": 16, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "key": { "type": "string", "minLength": 32, "maxLength": 256 } } }, "PublicTicketSeatHoldInput": { "type": "object", "additionalProperties": true, "required": [ "tenantSlug", "offeringId" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "PublicTicketSeatHoldCommandInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "token" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "PublicTicketSeatHoldChangeInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "token" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } } }, "PublicTicketSeatHoldSnapshot": { "type": "object", "additionalProperties": false, "required": [ "token", "status", "expiresAt", "quantity", "seatMapId" ], "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "active", "released", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "releasedAt": { "type": "string", "format": "date-time" } } }, "PublicTicketSeatHoldResult": { "type": "object", "additionalProperties": false, "required": [ "hold", "decision", "renewed", "expired" ], "properties": { "hold": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "decision": { "$ref": "#/components/schemas/SeatHoldDecision" }, "renewed": { "type": "boolean" }, "expired": { "type": "integer", "minimum": 0 } } }, "PublicTicketSeatHoldEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatHoldRenewResult": { "type": "object", "additionalProperties": false, "required": [ "hold", "holds", "renewed", "changed" ], "properties": { "hold": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "maxItems": 20, "minItems": 1 }, "renewed": { "type": "boolean", "const": true }, "changed": { "type": "integer", "minimum": 1 } } }, "PublicTicketSeatHoldRenewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldRenewResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatHoldReleaseResult": { "type": "object", "additionalProperties": false, "required": [ "token", "released", "alreadyReleased", "changed", "holds" ], "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 160 }, "released": { "type": "boolean" }, "alreadyReleased": { "type": "boolean" }, "changed": { "type": "integer", "minimum": 0 }, "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" } } } }, "PublicTicketSeatHoldReleaseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldReleaseResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatHoldChangeResult": { "type": "object", "additionalProperties": false, "required": [ "previousHold", "hold", "changed" ], "properties": { "previousHold": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "hold": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "changed": { "type": "boolean", "const": true } } }, "PublicTicketSeatHoldChangeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldChangeResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "Calendar": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "name", "status", "timezone", "leadTimeMinutes", "maxPartySize", "allowWaitlist", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "leadTimeMinutes": { "type": "integer", "minimum": 0, "maximum": 43200 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "allowWaitlist": { "type": "boolean" }, "settings": { "type": "object", "additionalProperties": true } } }, "CalendarCreateInput": { "type": "object", "additionalProperties": true, "required": [ "locationId", "name" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" }, "leadTimeMinutes": { "type": "integer", "minimum": 0, "maximum": 43200, "default": 120 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 8 }, "allowWaitlist": { "type": "boolean", "default": true }, "settings": { "type": "object", "additionalProperties": true } } }, "CalendarUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" }, "leadTimeMinutes": { "type": "integer", "minimum": 0, "maximum": 43200, "default": 120 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 8 }, "allowWaitlist": { "type": "boolean", "default": true }, "settings": { "type": "object", "additionalProperties": true } } }, "CalendarEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Calendar" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CalendarPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "CalendarPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CalendarPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AvailabilityRule": { "type": "object", "additionalProperties": false, "required": [ "weekdays", "startTime", "endTime" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "weekdays": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "active": { "type": "boolean", "default": true }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "AvailabilityException": { "type": "object", "additionalProperties": false, "required": [ "date" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "closed": { "type": "boolean", "default": false }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "BookingService": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "slug", "name", "durationMinutes", "bufferBeforeMinutes", "bufferAfterMinutes", "maxPartySize", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "reminderDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "leadMinutes", "preparationText" ], "properties": { "enabled": { "type": "boolean" }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "reminderDefaultsVersion": { "type": "integer", "minimum": 1, "readOnly": true }, "recoveryDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "delayMinutes", "validForDays", "invitationText" ], "properties": { "enabled": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "validForDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "invitationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "recoveryDefaultsVersion": { "type": "integer", "minimum": 1, "readOnly": true }, "whatsappDefaults": { "type": "object", "additionalProperties": false, "required": [ "confirmation", "reminder" ], "properties": { "confirmation": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." } } }, "reminder": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables", "leadMinutes" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." }, "leadMinutes": { "type": "integer", "minimum": 15, "maximum": 43200 } } } } }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingServiceCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "slug", "name", "durationMinutes" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440, "default": 0 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440, "default": 0 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "reminderDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "leadMinutes", "preparationText" ], "properties": { "enabled": { "type": "boolean" }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "recoveryDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "delayMinutes", "validForDays", "invitationText" ], "properties": { "enabled": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "validForDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "invitationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "whatsappDefaults": { "type": "object", "additionalProperties": false, "required": [ "confirmation", "reminder" ], "properties": { "confirmation": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." } } }, "reminder": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables", "leadMinutes" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." }, "leadMinutes": { "type": "integer", "minimum": 15, "maximum": 43200 } } } } }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingServiceUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440, "default": 0 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440, "default": 0 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "reminderDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "leadMinutes", "preparationText" ], "properties": { "enabled": { "type": "boolean" }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "recoveryDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "delayMinutes", "validForDays", "invitationText" ], "properties": { "enabled": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "validForDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "invitationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } }, "whatsappDefaults": { "type": "object", "additionalProperties": false, "required": [ "confirmation", "reminder" ], "properties": { "confirmation": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." } } }, "reminder": { "type": "object", "additionalProperties": false, "required": [ "enabled", "templateId", "variables", "leadMinutes" ], "properties": { "enabled": { "type": "boolean" }, "templateId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ], "description": "Tenant-owned approved WhatsAppTemplate; required while enabled." }, "variables": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "firstName", "guestName", "serviceName", "date", "time", "locationName", "address", "tenantName" ] }, "description": "Booking fact per template placeholder {{1}}…{{n}}." }, "leadMinutes": { "type": "integer", "minimum": 15, "maximum": 43200 } } } } }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingServiceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingService" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingServicePage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingService" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "BookingServicePageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingServicePage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingResource": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "kind", "slug", "name", "capacity", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "room", "staff", "equipment" ] }, "tenantMemberId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "availabilityRules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "weekdays", "startTime", "endTime" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "weekdays": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "active": { "type": "boolean", "default": true }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "maxItems": 100 }, "availabilityExceptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "closed": { "type": "boolean", "default": false }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "maxItems": 366 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingResourceCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "kind", "slug", "name" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantMemberId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "room", "staff", "equipment" ] }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "availabilityRules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "weekdays", "startTime", "endTime" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "weekdays": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "active": { "type": "boolean", "default": true }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "maxItems": 100, "default": [] }, "availabilityExceptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "closed": { "type": "boolean", "default": false }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "maxItems": 366, "default": [] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingResourceUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "tenantMemberId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "room", "staff", "equipment" ] }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "availabilityRules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "weekdays", "startTime", "endTime" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "weekdays": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] } }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "active": { "type": "boolean", "default": true }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "maxItems": 100, "default": [] }, "availabilityExceptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "closed": { "type": "boolean", "default": false }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "maxItems": 366, "default": [] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "metadata": { "type": "object", "additionalProperties": true } } }, "BookingResourceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingResource" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingResourcePage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResource" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "BookingResourcePageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingResourcePage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingResourceAllocation": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "bookingId", "resourceId", "quantity", "startsAt", "endsAt", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "released", "cancelled" ] }, "releasedAt": { "type": "string", "format": "date-time" } } }, "BookingResourceAllocationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingResourceAllocation" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingResourceAllocationPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResourceAllocation" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "BookingResourceAllocationPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingResourceAllocationPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CalendarServiceAssignment": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "calendarId", "serviceId", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "isDefault": { "type": "boolean" } } }, "CalendarServiceAssignmentCreateInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "serviceId" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "isDefault": { "type": "boolean", "default": false } } }, "CalendarServiceAssignmentUpdateInput": { "type": "object", "additionalProperties": false, "required": [ "isDefault" ], "properties": { "isDefault": { "type": "boolean" } } }, "CalendarServiceAssignmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CalendarServiceAssignment" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CalendarServiceAssignmentPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarServiceAssignment" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "CalendarServiceAssignmentPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CalendarServiceAssignmentPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CalendarResourceAssignment": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "calendarId", "resourceId", "requiredQuantity", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "requiredQuantity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "CalendarResourceAssignmentCreateInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "resourceId" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "requiredQuantity": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } }, "CalendarResourceAssignmentUpdateInput": { "type": "object", "additionalProperties": false, "required": [ "requiredQuantity" ], "properties": { "requiredQuantity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "CalendarResourceAssignmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CalendarResourceAssignment" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CalendarResourceAssignmentPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarResourceAssignment" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "CalendarResourceAssignmentPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CalendarResourceAssignmentPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "ResourceDeletionResult": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } }, "ResourceDeletionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ResourceDeletionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingCreateInput": { "type": "object", "additionalProperties": true, "required": [ "locationId", "calendarId", "guestName", "partySize", "startsAt", "endsAt" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "const": "pending", "default": "pending" }, "paymentStatus": { "type": "string", "enum": [ "notRequired", "pending", "paid", "refunded", "failed" ], "default": "notRequired" }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } }, "BookingUpdateInput": { "type": "object", "additionalProperties": true, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "paymentStatus": { "type": "string", "enum": [ "notRequired", "pending", "paid", "refunded", "failed" ], "default": "notRequired" }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } }, "BookingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "BookingPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailMessage": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "kind", "audience", "recipientEmail", "subject", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "templateId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "waitlistOffer", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice", "platformNotice", "conversationMessage", "followUpService", "followUpReactivation" ] }, "audience": { "type": "string", "enum": [ "direct", "bookingGuests", "ticketBuyers", "eventAttendees", "tenantMembers" ] }, "recipientEmail": { "type": "string", "format": "email" }, "recipientName": { "type": "string", "minLength": 1, "maxLength": 160 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "queued", "processing", "sent", "failed", "cancelled" ] }, "relatedBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedEventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedTicketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scheduledAt": { "type": "string", "format": "date-time" }, "queuedAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "providerMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "metadata": { "type": "object", "additionalProperties": true } } }, "SlotCapacityDecision": { "type": "object", "additionalProperties": false, "required": [ "ok", "reason", "capacity", "usedCapacity", "requestedPartySize", "projectedCapacity", "remainingCapacity", "overbookedSeats" ], "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "capacityAvailable", "overbookingAllowed", "invalidCapacity", "invalidPartySize", "invalidSlotWindow", "capacityExceeded", "overbookingLimitExceeded" ] }, "capacity": { "type": "integer" }, "usedCapacity": { "type": "integer" }, "requestedPartySize": { "type": "integer" }, "projectedCapacity": { "type": "integer" }, "remainingCapacity": { "type": "integer" }, "overbookedSeats": { "type": "integer" } } }, "WebhookEnqueueSummary": { "type": "object", "additionalProperties": false, "required": [ "queued", "deliveryIds" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "deliveryIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "skippedReason": { "type": "string", "const": "deliveryEnqueueFailed" } } }, "BookingWorkflowResult": { "type": "object", "additionalProperties": false, "required": [ "booking", "emailMessages", "mail", "webhooks" ], "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "capacity": { "$ref": "#/components/schemas/SlotCapacityDecision" }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "mail": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "missingGuestEmail", "unchangedStatus", "statusHasNoCustomerMail" ] } } }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "loyaltyAccrual": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "applied", "pending" ] }, "appended": { "type": "integer", "minimum": 0 }, "deduplicated": { "type": "integer", "minimum": 0 } } } } }, "BookingWorkflowEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingWorkflowResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingAttendanceCommandResult": { "type": "object", "additionalProperties": false, "required": [ "booking", "changed" ], "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "changed": { "type": "boolean" }, "event": { "$ref": "#/components/schemas/BookingAttendanceEvent" } } }, "BookingAttendanceCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingAttendanceCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingAttendanceHistory": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingAttendanceEvent" }, "maxItems": 100 } } }, "BookingAttendanceHistoryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingAttendanceHistory" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSlotPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BookingSlot" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "BookingSlotPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSlotPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSelfServiceBooking": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "guestName", "partySize", "startsAt", "endsAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "guestName": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestEmailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } }, "BookingSelfServiceCalendar": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "timezone", "maxPartySize" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "BookingSelfServiceLocation": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "BookingSelfServiceActions": { "type": "object", "additionalProperties": false, "required": [ "canCancel", "canReschedule", "cutoffMinutes", "tokenExpiresAt" ], "properties": { "canCancel": { "type": "boolean" }, "canReschedule": { "type": "boolean" }, "cutoffMinutes": { "type": "integer", "minimum": 0, "maximum": 43200 }, "tokenExpiresAt": { "type": "string", "format": "date-time" } } }, "BookingSelfServiceState": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "locale", "booking", "calendar", "location", "actions" ], "properties": { "tenantSlug": { "type": "string", "minLength": 1, "maxLength": 120 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "booking": { "$ref": "#/components/schemas/BookingSelfServiceBooking" }, "calendar": { "$ref": "#/components/schemas/BookingSelfServiceCalendar" }, "location": { "$ref": "#/components/schemas/BookingSelfServiceLocation" }, "actions": { "$ref": "#/components/schemas/BookingSelfServiceActions" } } }, "BookingSelfServiceStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSelfServiceState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSelfServiceMailSummary": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "missingGuestEmail", "unchangedStatus", "statusHasNoCustomerMail" ] } } }, "BookingSelfServiceCancelInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 24, "maxLength": 4096 }, "reason": { "type": "string", "minLength": 0, "maxLength": 1000 } } }, "BookingSelfServiceCancelResult": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "locale", "booking", "calendar", "location", "actions", "mail", "supportCaseId" ], "properties": { "tenantSlug": { "type": "string", "minLength": 1, "maxLength": 120 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "booking": { "$ref": "#/components/schemas/BookingSelfServiceBooking" }, "calendar": { "$ref": "#/components/schemas/BookingSelfServiceCalendar" }, "location": { "$ref": "#/components/schemas/BookingSelfServiceLocation" }, "actions": { "$ref": "#/components/schemas/BookingSelfServiceActions" }, "mail": { "$ref": "#/components/schemas/BookingSelfServiceMailSummary" }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BookingSelfServiceCancelEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSelfServiceCancelResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingSelfServiceRescheduleInput": { "type": "object", "additionalProperties": false, "required": [ "token", "startsAt", "endsAt" ], "properties": { "token": { "type": "string", "minLength": 24, "maxLength": 4096 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "minLength": 0, "maxLength": 1000 } } }, "BookingSelfServiceRescheduleResult": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "locale", "booking", "calendar", "location", "actions", "capacity", "mail", "supportCaseId" ], "properties": { "tenantSlug": { "type": "string", "minLength": 1, "maxLength": 120 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "booking": { "$ref": "#/components/schemas/BookingSelfServiceBooking" }, "calendar": { "$ref": "#/components/schemas/BookingSelfServiceCalendar" }, "location": { "$ref": "#/components/schemas/BookingSelfServiceLocation" }, "actions": { "$ref": "#/components/schemas/BookingSelfServiceActions" }, "capacity": { "$ref": "#/components/schemas/SlotCapacityDecision" }, "mail": { "$ref": "#/components/schemas/BookingSelfServiceMailSummary" }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BookingSelfServiceRescheduleEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSelfServiceRescheduleResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventBrandingTheme": { "type": "object", "additionalProperties": false, "required": [ "version", "layout", "colors", "overlayOpacity", "badgeStyle", "showGallery", "notice" ], "properties": { "version": { "type": "string", "const": "vsm-event-branding-v1" }, "layout": { "type": "string", "enum": [ "classic", "spotlight", "immersive" ] }, "colors": { "type": "object", "additionalProperties": false, "required": [ "accent", "surface", "text" ], "properties": { "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } } }, "overlayOpacity": { "type": "integer", "minimum": 0, "maximum": 80 }, "badgeStyle": { "type": "string", "enum": [ "solid", "outline", "soft" ] }, "showGallery": { "type": "boolean" }, "notice": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 280 }, { "type": "null" } ] } } }, "EventOrganizerCreateInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 220 }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 64 }, { "type": "null" } ] }, "websiteUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "notes": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] } } }, "EventOrganizerUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 220 }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "phone": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 64 }, { "type": "null" } ] }, "websiteUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "notes": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] } }, "minProperties": 1 }, "EventOrganizerListResult": { "type": "object", "additionalProperties": false, "required": [ "organizers" ], "properties": { "organizers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EventOrganizer" } } } }, "EventPublishResult": { "type": "object", "additionalProperties": false, "required": [ "event", "checklist", "unchanged", "webhooks" ], "properties": { "event": { "$ref": "#/components/schemas/Event" }, "checklist": { "type": "object", "additionalProperties": false, "required": [ "basics", "instances", "publicVisibility" ], "properties": { "basics": { "type": "boolean", "const": true }, "instances": { "type": "boolean", "const": true }, "publicVisibility": { "type": "boolean", "const": true } } }, "unchanged": { "type": "boolean" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "EventPublishEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventPublishResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventReminderInput": { "type": "object", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "recipients": { "type": "array", "maxItems": 5000, "items": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "EventNoticeInput": { "type": "object", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "recipients": { "type": "array", "maxItems": 5000, "items": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "changeSummary": { "type": "string", "minLength": 0, "maxLength": 5000 }, "reason": { "type": "string", "minLength": 0, "maxLength": 5000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "EventNoticeResult": { "type": "object", "additionalProperties": false, "required": [ "event", "messages", "mail", "recipients", "unchanged", "webhooks" ], "properties": { "event": { "$ref": "#/components/schemas/Event" }, "messages": { "type": "array", "maxItems": 5000, "items": { "$ref": "#/components/schemas/EmailMessage" } }, "mail": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "noRecipients", "alreadyArchived" ] } } }, "recipients": { "type": "object", "additionalProperties": false, "required": [ "direct", "bookingGuests", "ticketBuyers", "unique" ], "properties": { "direct": { "type": "integer", "minimum": 0 }, "bookingGuests": { "type": "integer", "minimum": 0 }, "ticketBuyers": { "type": "integer", "minimum": 0 }, "unique": { "type": "integer", "minimum": 0 } } }, "unchanged": { "type": "boolean" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "EventNoticeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventNoticeResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailBroadcastPreview": { "type": "object", "additionalProperties": false, "required": [ "audience", "recipientCount", "recipients", "warnings" ], "properties": { "audience": { "type": "string", "enum": [ "direct", "bookingGuests", "ticketBuyers", "eventAttendees", "tenantMembers" ] }, "recipientCount": { "type": "integer", "minimum": 0 }, "recipients": { "type": "array", "maxItems": 8, "items": { "type": "object", "additionalProperties": false, "required": [ "emailMasked" ], "properties": { "emailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "EventReminderResult": { "type": "object", "additionalProperties": false, "required": [ "queued", "messages", "cancelledPrevious", "preview", "webhooks", "broadcastPlanId", "replayed" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "messages": { "type": "array", "maxItems": 5000, "items": { "$ref": "#/components/schemas/EmailMessage" } }, "cancelledPrevious": { "type": "integer", "minimum": 0 }, "broadcastPlanId": { "type": "string", "minLength": 1, "maxLength": 160 }, "replayed": { "type": "boolean" }, "preview": { "type": "object", "additionalProperties": false, "required": [ "audience", "recipientCount", "recipients", "warnings" ], "properties": { "audience": { "type": "string", "enum": [ "direct", "bookingGuests", "ticketBuyers", "eventAttendees", "tenantMembers" ] }, "recipientCount": { "type": "integer", "minimum": 0 }, "recipients": { "type": "array", "maxItems": 8, "items": { "type": "object", "additionalProperties": false, "required": [ "emailMasked" ], "properties": { "emailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "EventReminderEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventReminderResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicEventLocation": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "slug", "name", "status", "timezone", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "PublicEventTicketType": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "priceAmount", "currency", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "priceAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vatRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "inventoryLimit": { "type": "integer", "minimum": 0 }, "maxPerOrder": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "sortOrder": { "type": "integer", "minimum": 0 } } }, "PublicEventTicketOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "title", "status", "currency", "platformFeeBps", "ticketTypes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "description": { "type": "string", "minLength": 0, "maxLength": 10000 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "saleStartsAt": { "type": "string", "format": "date-time" }, "saleEndsAt": { "type": "string", "format": "date-time" }, "totalLimit": { "type": "integer", "minimum": 0 }, "maxPerOrder": { "type": "integer", "minimum": 1 }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "seatPricing": { "type": "object", "additionalProperties": true }, "ticketTypes": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "priceAmount", "currency", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "priceAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "vatRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "inventoryLimit": { "type": "integer", "minimum": 0 }, "maxPerOrder": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "sortOrder": { "type": "integer", "minimum": 0 } } } } } }, "PublicTicketSeatTargetLayout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "PublicTicketSeatTarget": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } }, "PublicTicketSeatCanvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "PublicTicketSeatRoom": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "canvas", "targets" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "background": { "type": "object", "additionalProperties": true }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } } } } }, "PublicTicketSeatSelection": { "type": "object", "additionalProperties": false, "required": [ "seatMapId", "seatMapName", "canvas", "holdTtlSeconds", "targets" ], "properties": { "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapName": { "type": "string", "minLength": 1, "maxLength": 220 }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "holdTtlSeconds": { "type": "integer", "minimum": 1 }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } } }, "rooms": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "canvas", "targets" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "background": { "type": "object", "additionalProperties": true }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } } } } } }, "defaultRoomId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "PublicTicketOfferingAvailability": { "type": "object", "additionalProperties": false, "required": [ "offeringId", "totalReserved", "seatSelectionRequired", "ticketTypes" ], "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "totalReserved": { "type": "integer", "minimum": 0 }, "totalRemaining": { "type": "integer", "minimum": 0 }, "seatSelectionRequired": { "type": "boolean" }, "seatSelection": { "type": "object", "additionalProperties": false, "required": [ "seatMapId", "seatMapName", "canvas", "holdTtlSeconds", "targets" ], "properties": { "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapName": { "type": "string", "minLength": 1, "maxLength": 220 }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "holdTtlSeconds": { "type": "integer", "minimum": 1 }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } } }, "rooms": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "canvas", "targets" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } } }, "background": { "type": "object", "additionalProperties": true }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "capacity", "layout", "status", "heldQuantity", "assignedQuantity", "remaining" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "seat", "block" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 220 }, "capacity": { "type": "integer", "minimum": 1 }, "layout": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" } } }, "status": { "type": "string", "enum": [ "available", "held", "booked", "blocked" ] }, "heldQuantity": { "type": "integer", "minimum": 0 }, "assignedQuantity": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomId": { "type": "string", "minLength": 1, "maxLength": 160 }, "roomLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "blockLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "ordinal": { "type": "integer", "minimum": 1 }, "features": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "wheelchair-accessible", "companion-seat", "limited-mobility", "hearing-assistance", "restricted-view" ] } }, "frontDistance": { "type": "number", "minimum": 0 } } } } } } }, "defaultRoomId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "ticketTypes": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "reserved", "status" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "available", "low", "soldOut" ] } } } } } }, "PublicEventArtistExternalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "spotify": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "instagram": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "facebook": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "youtube": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "PublicEventArtistRelease": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "type": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "PublicEventArtist": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "genres", "externalLinks", "recentReleases" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "type": "string", "minLength": 0, "maxLength": 20000 }, "genres": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "thumbnailUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "externalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "spotify": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "instagram": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "facebook": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "youtube": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "recentReleases": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "type": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } }, "PublicEventLineup": { "type": "object", "additionalProperties": false, "required": [ "organizer", "artists" ], "properties": { "organizer": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, { "type": "null" } ] }, "artists": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "artistId", "sortOrder", "role", "artist" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "artistId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sortOrder": { "type": "integer", "minimum": 0 }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "setDurationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "stageName": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 220 }, "artist": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "genres", "externalLinks", "recentReleases" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "type": "string", "minLength": 0, "maxLength": 20000 }, "genres": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "thumbnailUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "externalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "spotify": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "instagram": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "facebook": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "youtube": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "recentReleases": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "type": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } } } } } } }, "PublicEventMedia": { "type": "object", "additionalProperties": false, "required": [ "id", "role", "sortOrder", "altText", "focalX", "focalY", "cropAspect", "width", "height", "url" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "hero", "gallery", "social" ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 }, "focalX": { "type": "integer", "minimum": 0, "maximum": 100 }, "focalY": { "type": "integer", "minimum": 0, "maximum": 100 }, "cropAspect": { "type": "string", "enum": [ "original", "wide", "square", "portrait" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "minLength": 1, "maxLength": 4096 } } }, "PublicEventNextInstance": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "startsAt", "timezone" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] }, "PublicEventDetail": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "event", "location", "ticketOfferings", "ticketAvailability", "lineup", "media", "branding", "nextInstance" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "event": { "$ref": "#/components/schemas/Event" }, "location": { "oneOf": [ { "$ref": "#/components/schemas/PublicEventLocation" }, { "type": "null" } ] }, "ticketOfferings": { "type": "array", "items": { "$ref": "#/components/schemas/PublicEventTicketOffering" } }, "ticketAvailability": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketOfferingAvailability" } }, "lineup": { "type": "object", "additionalProperties": false, "required": [ "organizer", "artists" ], "properties": { "organizer": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, { "type": "null" } ] }, "artists": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "artistId", "sortOrder", "role", "artist" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "artistId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sortOrder": { "type": "integer", "minimum": 0 }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "setDurationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "stageName": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 220 }, "artist": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "genres", "externalLinks", "recentReleases" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "type": "string", "minLength": 0, "maxLength": 20000 }, "genres": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "thumbnailUrl": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "externalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "spotify": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "instagram": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "facebook": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "youtube": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "recentReleases": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "type": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } } } } } } }, "media": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "role", "sortOrder", "altText", "focalX", "focalY", "cropAspect", "width", "height", "url" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "hero", "gallery", "social" ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 }, "focalX": { "type": "integer", "minimum": 0, "maximum": 100 }, "focalY": { "type": "integer", "minimum": 0, "maximum": 100 }, "cropAspect": { "type": "string", "enum": [ "original", "wide", "square", "portrait" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "minLength": 1, "maxLength": 4096 } } } }, "branding": { "$ref": "#/components/schemas/EventBrandingTheme" }, "nextInstance": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "startsAt", "timezone" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } }, "PublicEventDetailEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicEventDetail" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicEventListResult": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "location", "events", "page" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "location": { "$ref": "#/components/schemas/PublicEventLocation" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "PublicEventListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicEventListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicSecretEventResult": { "type": "object", "additionalProperties": false, "required": [ "detail", "access" ], "properties": { "detail": { "$ref": "#/components/schemas/PublicEventDetail" }, "access": { "type": "object", "additionalProperties": false, "required": [ "linkId", "slug" ], "properties": { "linkId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } } } }, "PublicSecretEventEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicSecretEventResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketType": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "priceAmount", "currency", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "priceAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "vatRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "inventoryLimit": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "maxPerOrder": { "type": "integer", "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "TicketOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "title", "status", "currency", "platformFeeBps", "ticketTypes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatMapId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "description": { "type": "string", "minLength": 0, "maxLength": 10000 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "saleStartsAt": { "type": "string", "format": "date-time" }, "saleEndsAt": { "type": "string", "format": "date-time" }, "totalLimit": { "type": "integer", "minimum": 0 }, "maxPerOrder": { "type": "integer", "minimum": 1, "maximum": 1000 }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 5000 }, "seatPricing": { "$ref": "#/components/schemas/SeatPricingDocument" }, "ticketTypes": { "type": "array", "items": { "$ref": "#/components/schemas/TicketType" }, "maxItems": 100, "minItems": 1 } } }, "TicketOfferingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOffering" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOfferingPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOffering" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "TicketOfferingPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOfferingPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOrderItemInput": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "quantity" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unitAmount": { "type": "integer", "minimum": 0 } } }, "TicketOrderItem": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "quantity" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unitAmount": { "type": "integer", "minimum": 0 }, "discountAmount": { "type": "integer", "minimum": 0 } } }, "TicketOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "buyerEmail", "currency", "totalAmount", "applicationFeeAmount", "status", "items", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretLinkId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "buyerName": { "type": "string", "minLength": 1, "maxLength": 160 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "subtotalAmount": { "type": "integer", "minimum": 0 }, "discountAmount": { "type": "integer", "minimum": 0 }, "totalAmount": { "type": "integer", "minimum": 0 }, "applicationFeeAmount": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "completed", "cancelled", "refunded", "failed" ] }, "stripeCheckoutId": { "type": "string", "minLength": 1, "maxLength": 255 }, "stripePaymentIntent": { "type": "string", "minLength": 1, "maxLength": 255 }, "checkoutUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "completedAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItem" }, "maxItems": 100, "minItems": 1 } } }, "Ticket": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "orderId", "ticketTypeId", "ticketNumber", "accessCode", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketNumber": { "type": "string", "minLength": 1, "maxLength": 160 }, "accessCode": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "qrPayload": { "type": "string", "minLength": 1, "maxLength": 4096 }, "noShowAt": { "type": "string", "format": "date-time" }, "checkedInAt": { "type": "string", "format": "date-time" }, "checkedInByUserId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketInventorySnapshot": { "type": "object", "additionalProperties": false, "required": [ "totalReserved", "perTicketTypeReserved" ], "properties": { "totalReserved": { "type": "integer", "minimum": 0 }, "perTicketTypeReserved": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "TicketInventoryAcceptedDecision": { "type": "object", "additionalProperties": false, "required": [ "ok", "reason", "requestedQuantity", "projectedTotal", "snapshot" ], "properties": { "ok": { "type": "boolean", "const": true }, "reason": { "type": "string", "const": "inventoryAvailable" }, "requestedQuantity": { "type": "integer", "minimum": 0 }, "projectedTotal": { "type": "integer", "minimum": 0 }, "snapshot": { "$ref": "#/components/schemas/TicketInventorySnapshot" }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketInventoryRejectedDecision": { "type": "object", "additionalProperties": false, "required": [ "ok", "reason", "requestedQuantity", "projectedTotal", "snapshot" ], "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "offeringNotPublished", "unknownTicketType", "inactiveTicketType", "invalidQuantity", "maxPerOrderExceeded", "ticketTypeMaxPerOrderExceeded", "totalInventoryExceeded", "ticketTypeInventoryExceeded" ] }, "requestedQuantity": { "type": "integer", "minimum": 0 }, "projectedTotal": { "type": "integer", "minimum": 0 }, "snapshot": { "$ref": "#/components/schemas/TicketInventorySnapshot" }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketInventoryDecision": { "oneOf": [ { "$ref": "#/components/schemas/TicketInventoryAcceptedDecision" }, { "$ref": "#/components/schemas/TicketInventoryRejectedDecision" } ] }, "TicketPendingCheckout": { "type": "object", "additionalProperties": false, "required": [ "mode", "requiresWebhookFulfillment" ], "properties": { "mode": { "type": "string", "const": "stripe_checkout_pending" }, "requiresWebhookFulfillment": { "type": "boolean", "const": true } } }, "TicketCheckoutConnect": { "type": "object", "additionalProperties": false, "required": [ "chargeType", "applicationFeeAmount" ], "properties": { "chargeType": { "type": "string", "enum": [ "destination_charge", "platform_charge" ] }, "destinationAccount": { "type": "string", "minLength": 1, "maxLength": 255 }, "applicationFeeAmount": { "type": "integer", "minimum": 0 } } }, "TicketCheckoutSession": { "type": "object", "additionalProperties": false, "required": [ "mode", "id", "url", "requiresWebhookFulfillment", "connect" ], "properties": { "mode": { "type": "string", "const": "stripe_checkout" }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "paymentIntent": { "type": "string", "minLength": 1, "maxLength": 255 }, "requiresWebhookFulfillment": { "type": "boolean", "const": true }, "connect": { "type": "object", "additionalProperties": false, "required": [ "chargeType", "applicationFeeAmount" ], "properties": { "chargeType": { "type": "string", "enum": [ "destination_charge", "platform_charge" ] }, "destinationAccount": { "type": "string", "minLength": 1, "maxLength": 255 }, "applicationFeeAmount": { "type": "integer", "minimum": 0 } } } } }, "TicketOrderSeatHoldLinkResult": { "type": "object", "additionalProperties": false, "required": [ "linked" ], "properties": { "linked": { "type": "integer", "minimum": 0 }, "token": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketOrderCreateInput": { "type": "object", "additionalProperties": false, "required": [ "offeringId", "buyerEmail", "items" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "buyerName": { "type": "string", "minLength": 1, "maxLength": 160 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "applicationFeeAmount": { "type": "integer", "minimum": 0, "default": 0 }, "seatHoldToken": { "type": "string", "minLength": 1, "maxLength": 160 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItemInput" }, "maxItems": 100, "minItems": 1 } } }, "PublicTicketOrderCreateInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "buyerEmail", "items" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "buyerName": { "type": "string", "minLength": 1, "maxLength": 160 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "seatHoldToken": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionQuoteToken": { "type": "string", "minLength": 64, "maxLength": 160 }, "queueSessionToken": { "type": "string", "pattern": "^tq_[0-9a-f]{64}$" }, "queueBrowserKey": { "type": "string", "minLength": 16, "maxLength": 200 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "successUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "cancelUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItemInput" }, "maxItems": 100, "minItems": 1 } } }, "TicketCheckoutInput": { "type": "object", "additionalProperties": false, "properties": { "successUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "cancelUrl": { "type": "string", "format": "uri", "pattern": "^https?://" } } }, "TicketOrderCreateResult": { "type": "object", "additionalProperties": false, "required": [ "order", "inventory", "checkout", "seatHolds" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "inventory": { "$ref": "#/components/schemas/TicketInventoryAcceptedDecision" }, "checkout": { "$ref": "#/components/schemas/TicketPendingCheckout" }, "seatHolds": { "$ref": "#/components/schemas/TicketOrderSeatHoldLinkResult" } } }, "TicketOrderCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOrderCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketOrderCreateResult": { "type": "object", "additionalProperties": false, "required": [ "order", "inventory", "checkout", "seatHolds" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "inventory": { "$ref": "#/components/schemas/TicketInventoryAcceptedDecision" }, "checkout": { "$ref": "#/components/schemas/TicketCheckoutSession" }, "seatHolds": { "$ref": "#/components/schemas/TicketOrderSeatHoldLinkResult" } } }, "PublicTicketOrderCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketOrderCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketCheckoutResult": { "type": "object", "additionalProperties": false, "required": [ "order", "checkout" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "checkout": { "$ref": "#/components/schemas/TicketCheckoutSession" } } }, "TicketCheckoutEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketCheckoutResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOrderEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOrder" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOrderDetail": { "type": "object", "additionalProperties": false, "required": [ "order", "tickets", "seatAssignments" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "seatAssignments": { "type": "array", "items": { "$ref": "#/components/schemas/SeatAssignment" } } } }, "TicketOrderReadResult": { "oneOf": [ { "$ref": "#/components/schemas/TicketOrder" }, { "$ref": "#/components/schemas/TicketOrderDetail" } ] }, "TicketOrderReadEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOrderReadResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketSeatAssignmentResult": { "type": "object", "additionalProperties": false, "required": [ "assigned" ], "properties": { "assigned": { "type": "integer", "minimum": 0 }, "recoveredHolds": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "alreadyFulfilled", "noSeatHoldToken", "noActiveSeatHolds", "noTickets" ] } } }, "TicketFulfillmentResult": { "type": "object", "additionalProperties": false, "required": [ "order", "tickets", "emailMessages", "unchanged", "mail", "webhooks", "seatAssignments" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "unchanged": { "type": "boolean" }, "mail": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "const": "alreadyFulfilled" } } }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "seatAssignments": { "type": "object", "additionalProperties": false, "required": [ "assigned" ], "properties": { "assigned": { "type": "integer", "minimum": 0 }, "recoveredHolds": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "alreadyFulfilled", "noSeatHoldToken", "noActiveSeatHolds", "noTickets" ] } } } } }, "TicketFulfillmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketFulfillmentResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketMailResult": { "type": "object", "additionalProperties": false, "required": [ "order", "tickets", "emailMessages", "mail" ], "properties": { "order": { "$ref": "#/components/schemas/TicketOrder" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "mail": { "type": "object", "additionalProperties": false, "required": [ "queued", "workflow" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "workflow": { "type": "string", "const": "resend" } } } } }, "TicketMailEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketMailResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketInventoryAdjustmentListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "limit", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketInventoryAdjustment" }, "maxItems": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" } } }, "TicketInventoryAdjustmentListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketInventoryAdjustmentListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantCreateInput": { "type": "object", "additionalProperties": false, "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ], "default": "base" }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ], "default": "de" }, "defaultTimezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" }, "branding": { "type": "object", "additionalProperties": true } } }, "TenantUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ], "description": "Platform-Admin only. Operator package changes flow through Stripe Billing." }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ] }, "defaultTimezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "branding": { "type": "object", "additionalProperties": true } }, "minProperties": 1 }, "TenantPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthTenant" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "TenantPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthTenant" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantOnboardingCalendarDraft": { "type": "object", "additionalProperties": false, "required": [ "name", "leadTimeMinutes", "maxPartySize", "allowWaitlist" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "leadTimeMinutes": { "type": "integer", "minimum": 0, "maximum": 43200 }, "maxPartySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "allowWaitlist": { "type": "boolean" } } }, "TenantOnboardingState": { "type": "object", "additionalProperties": false, "required": [ "currentStep", "completedSteps", "locationId", "calendarId", "completedAt", "updatedAt" ], "properties": { "operatingMode": { "type": "string", "enum": [ "appointments", "classes_capacity", "events_general_admission", "events_reserved_seating" ] }, "journeyStep": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "completedJourneySteps": { "type": "array", "items": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "maxItems": 6, "minItems": 0, "uniqueItems": true }, "skippedJourneySteps": { "type": "array", "items": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "maxItems": 6, "minItems": 0, "uniqueItems": true }, "offeringDraft": { "$ref": "#/components/schemas/TenantOperatorOfferingDraft" }, "resourceKind": { "oneOf": [ { "type": "string", "enum": [ "calendar", "event" ] }, { "type": "null" } ] }, "resourceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "ticketOfferingId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "publishedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "testBookingStartedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "testBookingCompletedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "navigation": { "$ref": "#/components/schemas/TenantOperatorNavigationPreferences" }, "businessType": { "type": "string", "enum": [ "venue", "service", "restaurant" ] }, "targetPlan": { "type": "string", "enum": [ "base", "growth", "platform" ], "description": "Onboarding preference only; never grants plan entitlements." }, "currentStep": { "type": "string", "enum": [ "tenant", "team", "package", "location", "calendar", "finish" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "tenant", "team", "package", "location", "calendar", "finish" ] }, "maxItems": 6, "minItems": 0, "uniqueItems": true }, "locationId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "calendarId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "calendarDraft": { "$ref": "#/components/schemas/TenantOnboardingCalendarDraft" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TenantOnboardingUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "operatingMode": { "type": "string", "enum": [ "appointments", "classes_capacity", "events_general_admission", "events_reserved_seating" ] }, "journeyStep": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "completedJourneySteps": { "type": "array", "items": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "maxItems": 6, "minItems": 0, "uniqueItems": true }, "skippedJourneySteps": { "type": "array", "items": { "type": "string", "enum": [ "mode", "business", "location", "offering", "publish", "test_booking" ] }, "maxItems": 6, "minItems": 0, "uniqueItems": true }, "offeringDraft": { "$ref": "#/components/schemas/TenantOperatorOfferingDraft" }, "resourceKind": { "oneOf": [ { "type": "string", "enum": [ "calendar", "event" ] }, { "type": "null" } ] }, "resourceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "ticketOfferingId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "publishedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "testBookingStartedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "testBookingCompletedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "navigation": { "$ref": "#/components/schemas/TenantOperatorNavigationPreferences" }, "businessType": { "type": "string", "enum": [ "venue", "service", "restaurant" ] }, "targetPlan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "currentStep": { "type": "string", "enum": [ "tenant", "team", "package", "location", "calendar", "finish" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "tenant", "team", "package", "location", "calendar", "finish" ] }, "maxItems": 6, "minItems": 0 }, "locationId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "calendarId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "calendarDraft": { "$ref": "#/components/schemas/TenantOnboardingCalendarDraft" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TenantOnboardingResult": { "type": "object", "additionalProperties": false, "required": [ "tenant", "state" ], "properties": { "tenant": { "$ref": "#/components/schemas/AuthTenant" }, "state": { "$ref": "#/components/schemas/TenantOnboardingState" } } }, "TenantOnboardingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantOnboardingResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantMemberCreateInput": { "type": "object", "additionalProperties": false, "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "owner", "manager", "staff", "customer" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "TenantMemberUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "owner", "manager", "staff", "customer" ] } }, "minProperties": 1 }, "TenantInviteDelivery": { "type": "object", "additionalProperties": false, "required": [ "expiresAt", "tokenHash", "mailDelivery" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "tokenHash": { "type": "string", "minLength": 1, "maxLength": 255 }, "developmentToken": { "type": "string", "minLength": 16, "maxLength": 512 }, "mailDelivery": { "type": "string", "enum": [ "queued", "not_configured" ] }, "emailMessageId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TenantMemberInviteResult": { "type": "object", "additionalProperties": false, "required": [ "member", "invite" ], "properties": { "member": { "$ref": "#/components/schemas/AuthTenantMember" }, "invite": { "$ref": "#/components/schemas/TenantInviteDelivery" } } }, "TenantMemberInviteEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantMemberInviteResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantMemberEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthTenantMember" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantMemberPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthTenantMember" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "TenantMemberPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantMemberPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantLocationDeletedResult": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } }, "TenantLocationDeletedEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantLocationDeletedResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "Location": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "slug", "name", "status", "timezone", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "bookingForm": { "anyOf": [ { "$ref": "#/components/schemas/PublicBookingFormOptions" }, { "type": "null" } ], "description": "Optional location-wide form. Null inherits the tenant default; explicit calendar-bound entries keep their own settings." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "LocationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "default": "draft" }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "bookingForm": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "stepOrder": { "type": "string", "enum": [ "selection-first", "contact-first" ] }, "intro": { "type": "object", "additionalProperties": false, "properties": { "logoUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "pattern": "^https://" }, "title": { "type": "string", "minLength": 0, "maxLength": 120 }, "text": { "type": "string", "minLength": 0, "maxLength": 500 } } } } }, { "type": "null" } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "default": "Europe/Berlin" } } }, "LocationUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "bookingForm": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "stepOrder": { "type": "string", "enum": [ "selection-first", "contact-first" ] }, "intro": { "type": "object", "additionalProperties": false, "properties": { "logoUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "pattern": "^https://" }, "title": { "type": "string", "minLength": 0, "maxLength": 120 }, "text": { "type": "string", "minLength": 0, "maxLength": 500 } } } } }, { "type": "null" } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "minProperties": 1 }, "LocationPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "LocationPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LocationPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LocationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Location" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BillingLocalizedLabel": { "type": "object", "additionalProperties": false, "required": [ "de", "en" ], "properties": { "de": { "type": "string", "minLength": 1, "maxLength": 160 }, "en": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BillingPriceStatus": { "oneOf": [ { "$ref": "#/components/schemas/BillingVerifiedPrice" }, { "$ref": "#/components/schemas/BillingUnavailablePrice" } ] }, "BillingPlanProduct": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "checkoutSupported", "prices" ], "properties": { "key": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "label": { "$ref": "#/components/schemas/BillingLocalizedLabel" }, "checkoutSupported": { "type": "boolean" }, "prices": { "type": "object", "additionalProperties": false, "required": [ "monthly", "yearly" ], "properties": { "monthly": { "$ref": "#/components/schemas/BillingPriceStatus" }, "yearly": { "$ref": "#/components/schemas/BillingPriceStatus" } } } } }, "BillingAddOnProduct": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "feature", "price" ], "properties": { "key": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "label": { "$ref": "#/components/schemas/BillingLocalizedLabel" }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "price": { "$ref": "#/components/schemas/BillingPriceStatus" } } }, "BillingProductsResult": { "type": "object", "additionalProperties": false, "required": [ "apiVersion", "commercialTermsApproved", "commercialTerms", "plans", "addOns" ], "properties": { "apiVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "commercialTermsApproved": { "type": "boolean" }, "commercialTerms": { "$ref": "#/components/schemas/CommercialTermsContract" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPlanProduct" }, "maxItems": 3, "minItems": 3 }, "addOns": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAddOnProduct" }, "maxItems": 8, "minItems": 8 } } }, "BillingProductsEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingProductsResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BillingSubscriptionSnapshot": { "type": "object", "additionalProperties": false, "required": [ "status", "plan", "cancelAtPeriodEnd" ], "properties": { "status": { "type": "string", "enum": [ "incomplete", "trialing", "active", "pastDue", "canceled", "unpaid" ] }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" } } }, "BillingAddOnSnapshot": { "type": "object", "additionalProperties": false, "required": [ "key", "feature", "status", "stripePriceConfigured" ], "properties": { "key": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "status": { "type": "string", "enum": [ "active", "canceled", "expired" ] }, "stripePriceConfigured": { "type": "boolean" } } }, "BillingStatusResult": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "plan", "subscription", "addOns", "entitlements", "bookingUsage", "persistence" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "subscription": { "oneOf": [ { "$ref": "#/components/schemas/BillingSubscriptionSnapshot" }, { "type": "null" } ] }, "addOns": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAddOnSnapshot" }, "maxItems": 8, "minItems": 0 }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEntitlement" }, "maxItems": 13, "minItems": 0 }, "bookingUsage": { "oneOf": [ { "$ref": "#/components/schemas/BookingUsagePeriodView" }, { "type": "null" } ] }, "persistence": { "type": "string", "enum": [ "memory", "prisma" ] }, "trialEndsAt": { "type": "string", "format": "date-time" } } }, "BillingStatusEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingStatusResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "StripeConnectCapabilityStatus": { "type": "object", "additionalProperties": false, "properties": { "transfers": { "type": "string", "enum": [ "active", "pending", "restricted", "unsupported" ] }, "payouts": { "type": "string", "enum": [ "active", "pending", "restricted", "unsupported" ] } } }, "StripeConnectAccountResult": { "type": "object", "additionalProperties": false, "required": [ "account", "created" ], "properties": { "account": { "$ref": "#/components/schemas/StripeConnectStatus" }, "created": { "type": "boolean" } } }, "StripeConnectOnboardingLink": { "type": "object", "additionalProperties": false, "required": [ "url", "expiresAt", "livemode" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "expiresAt": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" } } }, "StripeConnectOnboardingResult": { "type": "object", "additionalProperties": false, "required": [ "account", "link" ], "properties": { "account": { "$ref": "#/components/schemas/StripeConnectStatus" }, "link": { "$ref": "#/components/schemas/StripeConnectOnboardingLink" } } }, "BillingCheckoutInput": { "type": "object", "additionalProperties": false, "properties": { "plan": { "type": "string", "const": "base", "default": "base" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ], "default": "monthly" }, "addOns": { "type": "array", "items": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "maxItems": 8, "minItems": 0, "uniqueItems": true, "default": [] }, "successUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "cancelUrl": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "BillingCheckoutLineItem": { "type": "object", "additionalProperties": false, "required": [ "priceId", "envKey" ], "properties": { "priceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "envKey": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BillingCheckoutResult": { "type": "object", "additionalProperties": false, "required": [ "url", "mode" ], "properties": { "url": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "mode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] } } }, "BillingCheckoutEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingCheckoutResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BillingPortalInput": { "type": "object", "additionalProperties": false, "properties": { "returnUrl": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "BillingPortalResult": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] } } }, "BillingPortalEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingPortalResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BillingEntitlementsResult": { "type": "object", "additionalProperties": false, "required": [ "entitlements" ], "properties": { "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEntitlement" }, "maxItems": 13, "minItems": 0 } } }, "BillingEntitlementsEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingEntitlementsResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BillingAddOnMutationResult": { "type": "object", "additionalProperties": false, "required": [ "action", "addOnKey", "activeAddOns", "entitlements", "webhookExpected" ], "properties": { "action": { "type": "string", "enum": [ "activated", "deactivated", "already_active", "already_inactive" ] }, "addOnKey": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "activeAddOns": { "type": "array", "items": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "maxItems": 8, "minItems": 0, "uniqueItems": true }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEntitlement" }, "maxItems": 13, "minItems": 0 }, "webhookExpected": { "type": "boolean" } } }, "BillingAddOnMutationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingAddOnMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "StripeWebhookEventInput": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "data" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 160 }, "api_version": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true, "required": [ "object" ], "properties": { "object": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } }, "BillingWebhookFulfillmentSynced": { "type": "object", "additionalProperties": false, "required": [ "action", "tenantId", "plan", "addOns", "subscriptionId", "status", "webhooks" ], "properties": { "action": { "type": "string", "const": "synced" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "addOns": { "type": "array", "items": { "type": "string", "enum": [ "calendar", "seatmaps", "ticketing", "embeds", "apiWebhooks", "loyalty", "eventCredits", "llmAssistant" ] }, "maxItems": 8, "minItems": 0, "uniqueItems": true }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "minLength": 1, "maxLength": 64 }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "BillingWebhookFulfillmentIgnored": { "type": "object", "additionalProperties": false, "required": [ "action", "reason" ], "properties": { "action": { "type": "string", "const": "ignored" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "BillingWebhookTicketFulfilled": { "type": "object", "additionalProperties": false, "required": [ "action", "tenantId", "ticketOrderId", "stripeCheckoutId", "tickets", "mailQueued" ], "properties": { "action": { "type": "string", "const": "fulfilled" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ticketOrderId": { "type": "string", "minLength": 1, "maxLength": 255 }, "stripeCheckoutId": { "type": "string", "minLength": 1, "maxLength": 255 }, "tickets": { "type": "integer", "minimum": 0 }, "mailQueued": { "type": "integer", "minimum": 0 } } }, "BillingWebhookTicketCancelled": { "type": "object", "additionalProperties": false, "required": [ "action", "tenantId", "ticketOrderId", "stripeCheckoutId", "reason" ], "properties": { "action": { "type": "string", "const": "cancelled" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ticketOrderId": { "type": "string", "minLength": 1, "maxLength": 255 }, "stripeCheckoutId": { "type": "string", "minLength": 1, "maxLength": 255 }, "reason": { "type": "string", "const": "checkout_expired" } } }, "BillingWebhookTicketRefundReconciled": { "type": "object", "additionalProperties": false, "required": [ "action", "ticketRefundId", "status" ], "properties": { "action": { "type": "string", "const": "ticket_refund_reconciled" }, "ticketRefundId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "BillingWebhookTicketDisputeReconciled": { "type": "object", "additionalProperties": false, "required": [ "action", "disputeId", "status", "idempotent" ], "properties": { "action": { "type": "string", "const": "ticket_dispute_reconciled" }, "disputeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "minLength": 1, "maxLength": 64 }, "idempotent": { "type": "boolean" } } }, "BillingWebhookEventCreditTopUpSucceeded": { "type": "object", "additionalProperties": false, "required": [ "action", "transactionId", "replayed" ], "properties": { "action": { "type": "string", "const": "event_credit_topup_succeeded" }, "transactionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "replayed": { "type": "boolean" } } }, "BillingWebhookEventCreditTopUpFailed": { "type": "object", "additionalProperties": false, "required": [ "action", "transactionId" ], "properties": { "action": { "type": "string", "const": "event_credit_topup_failed" }, "transactionId": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "BillingWebhookEventCreditChargeback": { "type": "object", "additionalProperties": false, "required": [ "action", "transactionId", "replayed" ], "properties": { "action": { "type": "string", "enum": [ "chargeback_applied", "chargeback_reversed" ] }, "transactionId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "replayed": { "type": "boolean" } } }, "BillingWebhookFulfillment": { "oneOf": [ { "$ref": "#/components/schemas/BillingWebhookFulfillmentSynced" }, { "$ref": "#/components/schemas/BillingWebhookFulfillmentIgnored" }, { "$ref": "#/components/schemas/BillingWebhookTicketFulfilled" }, { "$ref": "#/components/schemas/BillingWebhookTicketCancelled" }, { "$ref": "#/components/schemas/BillingWebhookTicketRefundReconciled" }, { "$ref": "#/components/schemas/BillingWebhookTicketDisputeReconciled" }, { "$ref": "#/components/schemas/BillingWebhookEventCreditTopUpSucceeded" }, { "$ref": "#/components/schemas/BillingWebhookEventCreditTopUpFailed" }, { "$ref": "#/components/schemas/BillingWebhookEventCreditChargeback" } ] }, "BillingStripeWebhookResult": { "type": "object", "additionalProperties": false, "required": [ "received", "duplicate", "stripeEventId", "type", "tenantId", "processedAt", "fulfillment" ], "properties": { "received": { "type": "boolean", "const": true }, "duplicate": { "type": "boolean" }, "stripeEventId": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "processedAt": { "type": "string", "format": "date-time" }, "fulfillment": { "$ref": "#/components/schemas/BillingWebhookFulfillment" } } }, "BillingStripeWebhookEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BillingStripeWebhookResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "ReportingAnalyticsQueryInput": { "type": "object", "required": [], "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 366 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "comparePrevious": { "type": "boolean", "default": true }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "enum": [ "all", "web", "phone", "walkIn", "internal", "ticket" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } }, "additionalProperties": false }, "ReportingAnalyticsMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingAnalyticsFilterOption": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 320 }, "parentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false }, "ReportingAnalyticsQuery": { "type": "object", "required": [ "from", "to", "comparePrevious", "source", "currency" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "comparePrevious": { "type": "boolean" }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "enum": [ "all", "web", "phone", "walkIn", "internal", "ticket" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": false }, "ReportingAnalyticsPeriod": { "type": "object", "required": [ "from", "to", "days", "timezone", "previousFrom", "previousTo", "comparePrevious" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "days": { "type": "integer", "minimum": 1 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 }, "previousFrom": { "type": "string", "format": "date-time" }, "previousTo": { "type": "string", "format": "date-time" }, "comparePrevious": { "type": "boolean" } }, "additionalProperties": false }, "ReportingAnalyticsFilters": { "type": "object", "required": [ "locations", "calendars", "events", "offerings", "currencies", "sources" ], "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsFilterOption" }, "minItems": 0 }, "calendars": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsFilterOption" }, "minItems": 0 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsFilterOption" }, "minItems": 0 }, "offerings": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsFilterOption" }, "minItems": 0 }, "currencies": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minItems": 0, "uniqueItems": true }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "all", "web", "phone", "walkIn", "internal", "ticket" ] }, "minItems": 0, "maxItems": 6, "uniqueItems": true } }, "additionalProperties": false }, "ReportingAnalyticsBookingsMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent", "partySize" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "partySize": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsTicketRevenueMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent", "currency", "grossAmount", "refundedAmount" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "grossAmount": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsUtilizationMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent", "occupied", "capacity" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "occupied": { "type": "integer", "minimum": 0 }, "capacity": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsConversionMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent", "successful", "attempts" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "successful": { "type": "integer", "minimum": 0 }, "attempts": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsCheckInsMetric": { "type": "object", "required": [ "value", "previousValue", "changePercent", "bookingCheckIns", "ticketCheckIns" ], "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "changePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bookingCheckIns": { "type": "integer", "minimum": 0 }, "ticketCheckIns": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsMetrics": { "type": "object", "required": [ "bookings", "ticketRevenue", "utilization", "conversion", "checkIns" ], "properties": { "bookings": { "$ref": "#/components/schemas/ReportingAnalyticsBookingsMetric" }, "ticketRevenue": { "$ref": "#/components/schemas/ReportingAnalyticsTicketRevenueMetric" }, "utilization": { "$ref": "#/components/schemas/ReportingAnalyticsUtilizationMetric" }, "conversion": { "$ref": "#/components/schemas/ReportingAnalyticsConversionMetric" }, "checkIns": { "$ref": "#/components/schemas/ReportingAnalyticsCheckInsMetric" } }, "additionalProperties": false }, "ReportingAnalyticsTimelineRow": { "type": "object", "required": [ "date", "bookings", "ticketOrders", "revenueAmount", "checkIns" ], "properties": { "date": { "type": "string", "format": "date" }, "bookings": { "type": "integer", "minimum": 0 }, "ticketOrders": { "type": "integer", "minimum": 0 }, "revenueAmount": { "type": "integer", "minimum": 0 }, "checkIns": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsBookingStatusRow": { "type": "object", "required": [ "status", "count", "percent" ], "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "count": { "type": "integer", "minimum": 0 }, "percent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "ReportingAnalyticsSourceRow": { "type": "object", "required": [ "source", "count", "percent" ], "properties": { "source": { "type": "string", "enum": [ "web", "phone", "walkIn", "internal", "ticket" ] }, "count": { "type": "integer", "minimum": 0 }, "percent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "ReportingAnalyticsSeatUtilization": { "type": "object", "required": [ "assigned", "activeHolds", "capacity", "percent", "offeringCount" ], "properties": { "assigned": { "type": "integer", "minimum": 0 }, "activeHolds": { "type": "integer", "minimum": 0 }, "capacity": { "type": "integer", "minimum": 0 }, "percent": { "type": "number", "minimum": 0, "maximum": 100 }, "offeringCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingAnalyticsTopItem": { "type": "object", "required": [ "id", "kind", "label", "bookings", "revenueAmount", "currency" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "calendar", "event", "offering" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 320 }, "bookings": { "type": "integer", "minimum": 0 }, "revenueAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": false }, "ReportingAnalyticsDefinitions": { "type": "object", "required": [ "bookings", "ticketRevenue", "utilization", "conversion", "seatUtilization" ], "properties": { "bookings": { "type": "string", "minLength": 1, "maxLength": 2000 }, "ticketRevenue": { "type": "string", "minLength": 1, "maxLength": 2000 }, "utilization": { "type": "string", "minLength": 1, "maxLength": 2000 }, "conversion": { "type": "string", "minLength": 1, "maxLength": 2000 }, "seatUtilization": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "additionalProperties": false }, "ReportingAnalyticsDataQuality": { "type": "object", "required": [ "isEmpty", "bookingRecords", "ticketOrderRecords", "definitions" ], "properties": { "isEmpty": { "type": "boolean" }, "bookingRecords": { "type": "integer", "minimum": 0 }, "ticketOrderRecords": { "type": "integer", "minimum": 0 }, "definitions": { "$ref": "#/components/schemas/ReportingAnalyticsDefinitions" } }, "additionalProperties": false }, "ReportingAnalyticsOverview": { "type": "object", "required": [ "schemaVersion", "generatedAt", "tenantId", "period", "query", "filters", "metrics", "timeline", "bookingStatuses", "sources", "seatUtilization", "topItems", "dataQuality" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-analytics-overview-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "period": { "$ref": "#/components/schemas/ReportingAnalyticsPeriod" }, "query": { "$ref": "#/components/schemas/ReportingAnalyticsQuery" }, "filters": { "$ref": "#/components/schemas/ReportingAnalyticsFilters" }, "metrics": { "$ref": "#/components/schemas/ReportingAnalyticsMetrics" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsTimelineRow" }, "minItems": 0 }, "bookingStatuses": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsBookingStatusRow" }, "minItems": 0, "maxItems": 5 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsSourceRow" }, "minItems": 0, "maxItems": 5 }, "seatUtilization": { "$ref": "#/components/schemas/ReportingAnalyticsSeatUtilization" }, "topItems": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingAnalyticsTopItem" }, "minItems": 0 }, "dataQuality": { "$ref": "#/components/schemas/ReportingAnalyticsDataQuality" } }, "additionalProperties": false }, "ReportingAnalyticsOverviewEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingAnalyticsOverview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingCampaignQueryInput": { "type": "object", "required": [], "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 366 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] } }, "additionalProperties": false }, "ReportingCampaignTotals": { "type": "object", "required": [ "campaigns", "resolvedRecipients", "excludedRecipients", "deliveries", "delivered", "failed", "suppressed", "pending", "cancelled", "opened", "clicked", "deliveryRateBps", "openRateBps", "clickRateBps" ], "properties": { "campaigns": { "type": "integer", "minimum": 0 }, "resolvedRecipients": { "type": "integer", "minimum": 0 }, "excludedRecipients": { "type": "integer", "minimum": 0 }, "deliveries": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "deliveryRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "openRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "clickRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false }, "ReportingCampaignChannelRow": { "type": "object", "required": [ "channel", "deliveries", "delivered", "failed", "suppressed", "pending", "cancelled", "opened", "clicked", "deliveryRateBps", "openRateBps", "clickRateBps" ], "properties": { "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "deliveries": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "deliveryRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "openRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "clickRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false }, "ReportingCampaignProviderRow": { "type": "object", "required": [ "provider", "attempts", "sent", "failed", "suppressed", "successRateBps", "state" ], "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 160 }, "attempts": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "successRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "state": { "type": "string", "enum": [ "healthy", "degraded", "failing" ] } }, "additionalProperties": false }, "ReportingCampaignRow": { "type": "object", "required": [ "id", "eventId", "eventTitle", "subject", "status", "channels", "scheduledAt", "completedAt", "resolvedRecipients", "excludedRecipients", "deliveries", "delivered", "failed", "suppressed", "opened", "clicked", "deliveryRateBps", "openRateBps", "clickRateBps" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventTitle": { "type": "string", "minLength": 1, "maxLength": 320 }, "subject": { "type": "string", "minLength": 1, "maxLength": 320 }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "partialFailed", "cancelled" ] }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "scheduledAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "resolvedRecipients": { "type": "integer", "minimum": 0 }, "excludedRecipients": { "type": "integer", "minimum": 0 }, "deliveries": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "suppressed": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 }, "deliveryRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "openRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "clickRateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false }, "ReportingCampaignFilters": { "type": "object", "required": [ "from", "to", "eventId", "channel" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "eventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "enum": [ "email", "inApp", "push" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingCampaignProviderReport": { "type": "object", "required": [ "contractVersion", "generatedAt", "filters", "totals", "channels", "providers", "campaigns" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-campaign-provider-report-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "filters": { "$ref": "#/components/schemas/ReportingCampaignFilters" }, "totals": { "$ref": "#/components/schemas/ReportingCampaignTotals" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingCampaignChannelRow" }, "minItems": 0, "maxItems": 3 }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingCampaignProviderRow" }, "minItems": 0 }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingCampaignRow" }, "minItems": 0, "maxItems": 50 } }, "additionalProperties": false }, "ReportingCampaignProviderReportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingCampaignProviderReport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingExportJobFilters": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "statuses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 0, "maxItems": 8, "uniqueItems": true } }, "additionalProperties": false }, "ReportingBookingExportFilters": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "minItems": 0, "maxItems": 5, "uniqueItems": true } }, "additionalProperties": false }, "ReportingTicketExportFilters": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "minItems": 0, "maxItems": 6, "uniqueItems": true } }, "additionalProperties": false }, "ReportingCustomerExportFilters": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "active", "archived", "merged" ] }, "minItems": 0, "maxItems": 3, "uniqueItems": true } }, "additionalProperties": false }, "ReportingFinanceExportFilters": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "statuses": { "type": "array", "items": { "type": "string", "enum": [ "pending", "completed", "cancelled", "refunded", "failed" ] }, "minItems": 0, "maxItems": 5, "uniqueItems": true } }, "additionalProperties": false }, "ReportingBookingExportInput": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "bookings" }, "format": { "type": "string", "const": "csv", "default": "csv" }, "filters": { "$ref": "#/components/schemas/ReportingBookingExportFilters", "default": {} } }, "additionalProperties": false }, "ReportingTicketExportInput": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "tickets" }, "format": { "type": "string", "const": "csv", "default": "csv" }, "filters": { "$ref": "#/components/schemas/ReportingTicketExportFilters", "default": {} } }, "additionalProperties": false }, "ReportingCustomerExportInput": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "customers" }, "format": { "type": "string", "const": "csv", "default": "csv" }, "filters": { "$ref": "#/components/schemas/ReportingCustomerExportFilters", "default": {} } }, "additionalProperties": false }, "ReportingFinanceExportInput": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "finance" }, "format": { "type": "string", "const": "csv", "default": "csv" }, "filters": { "$ref": "#/components/schemas/ReportingFinanceExportFilters", "default": {} } }, "additionalProperties": false }, "ReportingCreateExportJobInput": { "oneOf": [ { "$ref": "#/components/schemas/ReportingBookingExportInput" }, { "$ref": "#/components/schemas/ReportingTicketExportInput" }, { "$ref": "#/components/schemas/ReportingCustomerExportInput" }, { "$ref": "#/components/schemas/ReportingFinanceExportInput" } ], "discriminator": { "propertyName": "kind" } }, "ReportingExportJob": { "type": "object", "required": [ "id", "tenantId", "requestedByUserId", "kind", "format", "status", "filters", "filename", "contentType", "sizeBytes", "sha256", "rowCount", "attemptCount", "errorCode", "errorMessage", "startedAt", "completedAt", "failedAt", "expiresAt", "downloadedAt", "downloadCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "requestedByUserId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "bookings", "tickets", "customers", "finance" ] }, "format": { "type": "string", "const": "csv" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "expired" ] }, "filters": { "$ref": "#/components/schemas/ReportingExportJobFilters" }, "filename": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "contentType": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "sizeBytes": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "rowCount": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "downloadedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "downloadCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReportingExportJobList": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingExportJob" }, "minItems": 0, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingExportJobListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingExportJobList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingExportJobMutationResult": { "type": "object", "required": [ "job", "deduplicated" ], "properties": { "job": { "$ref": "#/components/schemas/ReportingExportJob" }, "deduplicated": { "type": "boolean" } }, "additionalProperties": false }, "ReportingExportJobMutationEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingExportJobMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingExportJobResult": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/ReportingExportJob" } }, "additionalProperties": false }, "ReportingExportJobEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingExportJobResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingTicketPayoutQueryInput": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": false }, "ReportingPayoutBookAmounts": { "type": "object", "required": [ "grossAmount", "refundedAmount", "grossPlatformFeeAmount", "refundedPlatformFeeAmount", "netPlatformFeeAmount", "lostDisputeAmount", "openDisputeAmount", "expectedNetAmount" ], "properties": { "grossAmount": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "integer", "minimum": 0 }, "grossPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "refundedPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "netPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "lostDisputeAmount": { "type": "integer", "minimum": 0 }, "openDisputeAmount": { "type": "integer", "minimum": 0 }, "expectedNetAmount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReportingPayoutSummary": { "type": "object", "required": [ "grossAmount", "refundedAmount", "grossPlatformFeeAmount", "refundedPlatformFeeAmount", "netPlatformFeeAmount", "lostDisputeAmount", "openDisputeAmount", "expectedNetAmount", "currency", "paidOrderCount", "succeededRefundCount", "openDisputeCount", "providerNetAmount", "allocatedPayoutNetAmount", "unmatchedPayoutNetAmount", "providerDriftAmount", "payoutDriftAmount", "providerState" ], "properties": { "grossAmount": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "integer", "minimum": 0 }, "grossPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "refundedPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "netPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "lostDisputeAmount": { "type": "integer", "minimum": 0 }, "openDisputeAmount": { "type": "integer", "minimum": 0 }, "expectedNetAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "paidOrderCount": { "type": "integer", "minimum": 0 }, "succeededRefundCount": { "type": "integer", "minimum": 0 }, "openDisputeCount": { "type": "integer", "minimum": 0 }, "providerNetAmount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "allocatedPayoutNetAmount": { "type": "integer" }, "unmatchedPayoutNetAmount": { "type": "integer" }, "providerDriftAmount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "payoutDriftAmount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "providerState": { "type": "string", "enum": [ "notConfigured", "notSynced", "matched", "drift" ] } }, "additionalProperties": false }, "ReportingPayoutRow": { "type": "object", "required": [ "grossAmount", "refundedAmount", "grossPlatformFeeAmount", "refundedPlatformFeeAmount", "netPlatformFeeAmount", "lostDisputeAmount", "openDisputeAmount", "expectedNetAmount", "offeringId", "offeringTitle", "eventId", "eventTitle", "currency", "paidOrderCount", "providerNetAmount", "allocatedPayoutNetAmount", "driftAmount" ], "properties": { "grossAmount": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "integer", "minimum": 0 }, "grossPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "refundedPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "netPlatformFeeAmount": { "type": "integer", "minimum": 0 }, "lostDisputeAmount": { "type": "integer", "minimum": 0 }, "openDisputeAmount": { "type": "integer", "minimum": 0 }, "expectedNetAmount": { "type": "integer", "minimum": 0 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringTitle": { "type": "string", "minLength": 1, "maxLength": 320 }, "eventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "eventTitle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "paidOrderCount": { "type": "integer", "minimum": 0 }, "providerNetAmount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "allocatedPayoutNetAmount": { "type": "integer" }, "driftAmount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingPayout": { "type": "object", "required": [ "id", "providerPayoutId", "status", "currency", "amount", "matchedNetAmount", "unmatchedNetAmount", "transactionCount", "arrivalAt", "providerCreatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "providerPayoutId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "inTransit", "paid", "failed", "cancelled" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "integer" }, "matchedNetAmount": { "type": "integer" }, "unmatchedNetAmount": { "type": "integer" }, "transactionCount": { "type": "integer", "minimum": 0 }, "arrivalAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "providerCreatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReportingPayoutReconciliation": { "type": "object", "required": [ "id", "status", "from", "to", "attemptCount", "settlementsScanned", "settlementsMatched", "settlementsDrifted", "payoutsScanned", "transactionsScanned", "unmatchedTransactions", "failureCode", "failureMessage", "startedAt", "completedAt", "failedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "attemptCount": { "type": "integer", "minimum": 0 }, "settlementsScanned": { "type": "integer", "minimum": 0 }, "settlementsMatched": { "type": "integer", "minimum": 0 }, "settlementsDrifted": { "type": "integer", "minimum": 0 }, "payoutsScanned": { "type": "integer", "minimum": 0 }, "transactionsScanned": { "type": "integer", "minimum": 0 }, "unmatchedTransactions": { "type": "integer", "minimum": 0 }, "failureCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "failureMessage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReportingTicketPayoutFilters": { "type": "object", "required": [ "from", "to", "eventId", "offeringId", "currency" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "eventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "offeringId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingTicketPayoutReport": { "type": "object", "required": [ "contractVersion", "generatedAt", "filters", "summaries", "rows", "payouts", "lastReconciliation" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-payout-report-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "filters": { "$ref": "#/components/schemas/ReportingTicketPayoutFilters" }, "summaries": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingPayoutSummary" }, "minItems": 0 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingPayoutRow" }, "minItems": 0 }, "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingPayout" }, "minItems": 0 }, "lastReconciliation": { "anyOf": [ { "$ref": "#/components/schemas/ReportingPayoutReconciliation" }, { "type": "null" } ] } }, "additionalProperties": false }, "ReportingTicketPayoutReportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingTicketPayoutReport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingPayoutReconciliationInput": { "type": "object", "required": [], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReportingPayoutReconciliationMutationResult": { "type": "object", "required": [ "reconciliation", "idempotent" ], "properties": { "reconciliation": { "$ref": "#/components/schemas/ReportingPayoutReconciliation" }, "idempotent": { "type": "boolean" } }, "additionalProperties": false }, "ReportingPayoutReconciliationMutationEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingPayoutReconciliationMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingPayoutReconciliationResult": { "type": "object", "required": [ "reconciliation" ], "properties": { "reconciliation": { "$ref": "#/components/schemas/ReportingPayoutReconciliation" } }, "additionalProperties": false }, "ReportingPayoutReconciliationEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ReportingPayoutReconciliationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ReportingCsvArtifact": { "type": "string", "description": "UTF-8 CSV bytes served with private no-store attachment headers" }, "CustomerAccountAccessInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "redirectPath": { "type": "string", "minLength": 1, "maxLength": 700 } } }, "CustomerAccountAccessResult": { "type": "object", "additionalProperties": false, "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean", "const": true }, "developmentToken": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "CustomerAccountAccessEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountAccessResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountPreferencesInput": { "type": "object", "additionalProperties": false, "properties": { "bookingRemindersEnabled": { "type": "boolean" }, "eventUpdatesEnabled": { "type": "boolean" }, "eventEmailEnabled": { "type": "boolean" }, "eventInAppEnabled": { "type": "boolean" }, "eventPushEnabled": { "type": "boolean" }, "accountMessagesEnabled": { "type": "boolean" } }, "minProperties": 1 }, "CustomerAccountPreferences": { "type": "object", "additionalProperties": false, "required": [ "bookingRemindersEnabled", "eventUpdatesEnabled", "eventEmailEnabled", "eventInAppEnabled", "eventPushEnabled", "accountMessagesEnabled", "updatedAt" ], "properties": { "bookingRemindersEnabled": { "type": "boolean" }, "eventUpdatesEnabled": { "type": "boolean" }, "eventEmailEnabled": { "type": "boolean" }, "eventInAppEnabled": { "type": "boolean" }, "eventPushEnabled": { "type": "boolean" }, "accountMessagesEnabled": { "type": "boolean" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerAccountPreferencesResult": { "type": "object", "additionalProperties": false, "required": [ "preferences" ], "properties": { "preferences": { "$ref": "#/components/schemas/CustomerAccountPreferences" } } }, "CustomerAccountPreferencesEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountPreferencesResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountDeletionRequestInput": { "type": "object", "additionalProperties": false, "required": [ "confirmEmail" ], "properties": { "confirmEmail": { "type": "string", "format": "email", "maxLength": 320 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "CustomerAccountDeletionCancelInput": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 256 } } }, "CustomerAccountDeletionStatusQuery": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 256 } } }, "CustomerAccountDeletionStatus": { "type": "object", "additionalProperties": false, "required": [ "requestId", "status", "requestedAt", "scheduledAt", "cancelledAt", "completedAt", "failedAt", "nextAttemptAt", "attempts", "canCancel" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "processing", "failed", "completed", "cancelled" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "scheduledAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "nextAttemptAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "integer", "minimum": 0 }, "canCancel": { "type": "boolean" } } }, "CustomerAccountDeletionRecovery": { "type": "object", "additionalProperties": false, "required": [ "deletion" ], "properties": { "deletion": { "oneOf": [ { "$ref": "#/components/schemas/CustomerAccountDeletionStatus" }, { "type": "null" } ] }, "gracePeriodDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "recoveryUrl": { "type": "string", "format": "uri", "maxLength": 2000 }, "recoveryCodeExpiresAt": { "type": "string", "format": "date-time" }, "revokedSessions": { "type": "integer", "minimum": 0 }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "CustomerAccountDeletionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountDeletionRecovery" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountBookingCancelInput": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 0, "maxLength": 1000 } } }, "CustomerAccountBookingRescheduleInput": { "type": "object", "additionalProperties": false, "required": [ "startsAt", "endsAt" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "minLength": 0, "maxLength": 1000 } } }, "CustomerAccountBookingMailSummary": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "missingGuestEmail", "unchangedStatus", "statusHasNoCustomerMail" ] } } }, "CustomerAccountBookingLoyaltyAccrual": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "applied", "pending" ] }, "appended": { "type": "integer", "minimum": 0 }, "deduplicated": { "type": "integer", "minimum": 0 } } }, "CustomerAccountBookingCommandResult": { "type": "object", "additionalProperties": false, "required": [ "booking", "emailMessages", "mail", "webhooks", "supportCaseId" ], "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "capacity": { "$ref": "#/components/schemas/SlotCapacityDecision" }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "mail": { "$ref": "#/components/schemas/CustomerAccountBookingMailSummary" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "loyaltyAccrual": { "$ref": "#/components/schemas/CustomerAccountBookingLoyaltyAccrual" }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "CustomerAccountBookingCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountBookingCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventInstance": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "startsAt", "endsAt", "timezone", "cancelled" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 }, "cancelled": { "type": "boolean" } } }, { "type": "null" } ] }, "CustomerAccountTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "defaultLocale", "defaultTimezone", "branding" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ] }, "defaultTimezone": { "type": "string", "minLength": 1, "maxLength": 160 }, "branding": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "CustomerAccountCustomer": { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "primaryEmail", "primaryPhone", "locale", "emailVerifiedAt", "marketingConsentStatus", "lastActivityAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 }, "primaryPhone": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "locale": { "oneOf": [ { "type": "string", "enum": [ "de", "en" ] }, { "type": "null" } ] }, "emailVerifiedAt": { "type": "string", "format": "date-time" }, "marketingConsentStatus": { "type": "string", "enum": [ "unknown", "granted", "denied" ] }, "lastActivityAt": { "type": "string", "format": "date-time" } } }, "CustomerAccountBooking": { "type": "object", "additionalProperties": false, "required": [ "id", "guestName", "partySize", "status", "startsAt", "endsAt", "createdAt", "location", "calendar", "service" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 1, "maxLength": 320 }, "partySize": { "type": "integer", "minimum": 1 }, "canManage": { "type": "boolean", "description": "Current personal booking management authority; the server rechecks it for every command." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "location": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "calendar": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "service": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, { "type": "null" } ] } } }, "CustomerAccountTicket": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "status", "accessCode", "qrPayload", "checkedInAt", "holderAssignedAt", "accessCodeRotatedAt", "createdAt", "ticketType", "eventInstance", "seatAssignment" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketNumber": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "accessCode": { "type": "string", "minLength": 1, "maxLength": 512 }, "qrPayload": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "checkedInAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "holderAssignedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "accessCodeRotatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "ticketType": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "eventInstance": { "$ref": "#/components/schemas/CustomerAccountEventInstance" }, "seatAssignment": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "seatLabel" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "seatLabel": { "type": "string", "minLength": 1, "maxLength": 160 } } }, { "type": "null" } ] } } }, "CustomerAccountOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug", "event", "eventInstance", "location" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "oneOf": [ { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, { "type": "null" } ] }, "event": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }, { "type": "null" } ] }, "eventInstance": { "$ref": "#/components/schemas/CustomerAccountEventInstance" }, "location": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 } } }, { "type": "null" } ] } } }, "CustomerAccountTicketOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "totalAmount", "currency", "createdAt", "offering", "tickets" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "completed", "cancelled", "refunded", "failed" ] }, "totalAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "createdAt": { "type": "string", "format": "date-time" }, "offering": { "$ref": "#/components/schemas/CustomerAccountOffering" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountTicket" }, "maxItems": 100 } } }, "CustomerAccountEventAlert": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "deliveredAt", "openedAt", "clickedAt", "template", "subject", "bodyText", "ctaLabel", "ctaUrl", "event" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "const": "delivered" }, "deliveredAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "clickedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "template": { "type": "string", "enum": [ "publish", "update", "cancelled", "reminder", "lowInventory", "custom" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 320 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "ctaLabel": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "ctaUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2000 }, { "type": "null" } ] }, "event": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } } } }, "CustomerAccount": { "type": "object", "additionalProperties": false, "required": [ "tenant", "customer", "preferences", "bookings", "bookingsTruncated", "ticketOrders", "ticketOrdersTruncated", "eventAlerts", "eventAlertsTruncated", "deletionRequest" ], "properties": { "tenant": { "$ref": "#/components/schemas/CustomerAccountTenant" }, "customer": { "$ref": "#/components/schemas/CustomerAccountCustomer" }, "preferences": { "$ref": "#/components/schemas/CustomerAccountPreferences" }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountBooking" }, "maxItems": 50 }, "bookingsTruncated": { "type": "boolean" }, "ticketOrders": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountTicketOrder" }, "maxItems": 50 }, "ticketOrdersTruncated": { "type": "boolean" }, "eventAlerts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEventAlert" }, "maxItems": 50 }, "eventAlertsTruncated": { "type": "boolean" }, "deletionRequest": { "oneOf": [ { "$ref": "#/components/schemas/CustomerAccountDeletionStatus" }, { "type": "null" } ] } } }, "CustomerAccountResult": { "type": "object", "additionalProperties": false, "required": [ "account" ], "properties": { "account": { "$ref": "#/components/schemas/CustomerAccount" } } }, "CustomerAccountEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountTicketTransferCreateInput": { "type": "object", "additionalProperties": false, "required": [ "recipientEmail" ], "properties": { "recipientEmail": { "type": "string", "format": "email", "maxLength": 320 }, "message": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "CustomerAccountTicketTransferOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug", "event", "eventInstance", "location" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "oneOf": [ { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, { "type": "null" } ] }, "event": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }, { "type": "null" } ] }, "eventInstance": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "startsAt", "endsAt", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 } } }, { "type": "null" } ] }, "location": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }, { "type": "null" } ] } } }, "CustomerAccountTicketTransfer": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketId", "direction", "status", "recipientEmailMasked", "senderName", "recipientName", "offering", "ticket", "message", "expiresAt", "acceptedAt", "declinedAt", "revokedAt", "expiredAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketId": { "type": "string", "minLength": 1, "maxLength": 160 }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "recipientEmailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "senderName": { "type": "string", "minLength": 1, "maxLength": 320 }, "recipientName": { "type": "string", "minLength": 1, "maxLength": 320 }, "offering": { "$ref": "#/components/schemas/CustomerAccountTicketTransferOffering" }, "ticket": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "status", "ticketType", "seatLabel", "accessCodeRotatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketNumber": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "ticketType": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "seatLabel": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "accessCodeRotatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "message": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "declinedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerAccountTicketTransfers": { "type": "object", "additionalProperties": false, "required": [ "incoming", "outgoing" ], "properties": { "incoming": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountTicketTransfer" }, "maxItems": 100 }, "outgoing": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountTicketTransfer" }, "maxItems": 100 } } }, "CustomerAccountTicketTransfersResult": { "type": "object", "additionalProperties": false, "required": [ "transfers" ], "properties": { "transfers": { "$ref": "#/components/schemas/CustomerAccountTicketTransfers" } } }, "CustomerAccountTicketTransfersEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountTicketTransfersResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountTicketTransferCommandResult": { "type": "object", "additionalProperties": false, "required": [ "transfer", "replayed" ], "properties": { "transfer": { "$ref": "#/components/schemas/CustomerAccountTicketTransfer" }, "replayed": { "type": "boolean" } } }, "CustomerAccountTicketTransferCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountTicketTransferCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountTicketPdf": { "type": "string", "format": "binary" }, "CustomerAccountPublicTicketTransfer": { "type": "object", "additionalProperties": false, "required": [ "tenant", "transfer", "ticket" ], "properties": { "tenant": { "type": "object", "additionalProperties": false, "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" } } }, "transfer": { "type": "object", "additionalProperties": false, "required": [ "status", "senderName", "recipientEmailMasked", "message", "expiresAt", "createdAt" ], "properties": { "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "senderName": { "type": "string", "minLength": 1, "maxLength": 320 }, "recipientEmailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "message": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ticket": { "type": "object", "additionalProperties": false, "required": [ "ticketNumberMasked", "ticketTypeName", "seatLabel", "offeringTitle", "eventTitle", "locationName", "eventInstance" ], "properties": { "ticketNumberMasked": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeName": { "type": "string", "minLength": 1, "maxLength": 320 }, "seatLabel": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "offeringTitle": { "type": "string", "minLength": 1, "maxLength": 320 }, "eventTitle": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "locationName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "eventInstance": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "startsAt", "endsAt", "timezone" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 160 } } }, { "type": "null" } ] } } } } }, "CustomerAccountPublicTicketTransferEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountPublicTicketTransfer" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyRuleInput": { "type": "object", "additionalProperties": false, "required": [ "trigger", "label", "stampsAwarded" ], "properties": { "trigger": { "type": "string", "enum": [ "bookingCompleted", "ticketRedeemed", "manual", "couponRedeemed" ] }, "triggerReferenceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "stampsAwarded": { "type": "integer", "minimum": 1, "maximum": 100 }, "enabled": { "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "LoyaltyProgramCreateInput": { "type": "object", "additionalProperties": false, "required": [ "title", "requiredStamps", "rewardDescription", "rules" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "requiredStamps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rewardDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyRuleInput" }, "maxItems": 25, "minItems": 1 } } }, "LoyaltyProgramUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "requiredStamps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rewardDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyRuleInput" }, "maxItems": 25, "minItems": 1 } }, "minProperties": 1 }, "LoyaltyAdjustmentInput": { "type": "object", "additionalProperties": false, "required": [ "customerId", "delta", "note" ], "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "delta": { "type": "integer", "minimum": -1000, "maximum": 1000, "not": { "const": 0 } }, "note": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "LoyaltyStampTokenInput": { "type": "object", "additionalProperties": false, "properties": { "ruleId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 60 } } }, "LoyaltyRewardRedeemInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 256 } } }, "LoyaltyRewardVoidInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "CustomerLoyaltyStampInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 256 } } }, "LoyaltyProgramListQuery": { "type": "object", "additionalProperties": false, "properties": { "includeEnded": { "type": "boolean", "default": false } } }, "LoyaltyLedgerQuery": { "type": "object", "additionalProperties": false, "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } } }, "LoyaltyRewardQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "issued", "redeemed", "voided" ] } } }, "LoyaltyRule": { "type": "object", "additionalProperties": false, "required": [ "id", "trigger", "triggerReferenceId", "label", "stampsAwarded", "enabled", "sortOrder" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "trigger": { "type": "string", "enum": [ "booking_completed", "ticket_redeemed", "manual", "coupon_redeemed" ] }, "triggerReferenceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "stampsAwarded": { "type": "integer", "minimum": 1, "maximum": 100 }, "enabled": { "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "LoyaltyProgramMetrics": { "type": "object", "additionalProperties": false, "required": [ "participants", "openRewards", "ledgerEntries" ], "properties": { "participants": { "type": "integer", "minimum": 0 }, "openRewards": { "type": "integer", "minimum": 0 }, "ledgerEntries": { "type": "integer", "minimum": 0 } } }, "LoyaltyProgram": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "title", "description", "requiredStamps", "rewardDescription", "status", "validFrom", "validUntil", "activatedAt", "pausedAt", "endedAt", "createdAt", "updatedAt", "rules", "metrics" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "requiredStamps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rewardDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "activatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "pausedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyRule" }, "maxItems": 25 }, "metrics": { "$ref": "#/components/schemas/LoyaltyProgramMetrics" } } }, "LoyaltyCustomerSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "primaryEmail" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 } } }, "LoyaltyLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "customerId", "kind", "delta", "balanceAfter", "sourceType", "sourceId", "note", "occurredAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "programId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "earn", "adjustment", "reward_redemption", "reversal" ] }, "delta": { "type": "integer", "minimum": -1000000000, "maximum": 1000000000 }, "balanceAfter": { "type": "integer", "minimum": 0 }, "sourceType": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" } } }, "LoyaltyRewardProgramSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "LoyaltyReward": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "customerId", "status", "description", "redemptionTokenHint", "issuedAt", "redeemedAt", "voidedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "programId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "issued", "redeemed", "voided" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "redemptionTokenHint": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "issuedAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "voidedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" }, "program": { "$ref": "#/components/schemas/LoyaltyRewardProgramSummary" } } }, "LoyaltyWallet": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "customerId", "balance", "lifetimeEarned", "lifetimeRedeemed", "version", "lastActivityAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "programId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "balance": { "type": "integer", "minimum": 0 }, "lifetimeEarned": { "type": "integer", "minimum": 0 }, "lifetimeRedeemed": { "type": "integer", "minimum": 0 }, "version": { "type": "integer", "minimum": 0 }, "lastActivityAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "LoyaltyAppendResult": { "type": "object", "additionalProperties": false, "required": [ "entry", "wallet", "deduplicated" ], "properties": { "entry": { "$ref": "#/components/schemas/LoyaltyLedgerEntry" }, "wallet": { "$ref": "#/components/schemas/LoyaltyWallet" }, "deduplicated": { "type": "boolean" } } }, "LoyaltyStampToken": { "type": "object", "additionalProperties": false, "required": [ "id", "token", "tokenHint", "stamps", "expiresAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "token": { "type": "string", "minLength": 16, "maxLength": 256 }, "tokenHint": { "type": "string", "minLength": 1, "maxLength": 160 }, "stamps": { "type": "integer", "minimum": 1, "maximum": 100 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "LoyaltyRewardIssueResult": { "type": "object", "additionalProperties": false, "required": [ "reward", "redemptionToken", "deduplicated" ], "properties": { "reward": { "$ref": "#/components/schemas/LoyaltyReward" }, "redemptionToken": { "oneOf": [ { "type": "string", "minLength": 16, "maxLength": 256 }, { "type": "null" } ] }, "deduplicated": { "type": "boolean" } } }, "LoyaltyProgramResult": { "type": "object", "additionalProperties": false, "required": [ "program" ], "properties": { "program": { "$ref": "#/components/schemas/LoyaltyProgram" } } }, "LoyaltyProgramEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyProgramResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyProgramListResult": { "type": "object", "additionalProperties": false, "required": [ "programs" ], "properties": { "programs": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgram" }, "maxItems": 500 } } }, "LoyaltyProgramListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyProgramListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyLedgerListResult": { "type": "object", "additionalProperties": false, "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyLedgerEntry" }, "maxItems": 500 } } }, "LoyaltyLedgerListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyLedgerListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyRewardListResult": { "type": "object", "additionalProperties": false, "required": [ "rewards" ], "properties": { "rewards": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyReward" }, "maxItems": 500 } } }, "LoyaltyRewardListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyRewardListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyRewardResult": { "type": "object", "additionalProperties": false, "required": [ "reward" ], "properties": { "reward": { "$ref": "#/components/schemas/LoyaltyReward" } } }, "LoyaltyRewardEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyRewardResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyRewardVoidResult": { "type": "object", "additionalProperties": false, "required": [ "reward", "ledgerEntry" ], "properties": { "reward": { "$ref": "#/components/schemas/LoyaltyReward" }, "ledgerEntry": { "$ref": "#/components/schemas/LoyaltyLedgerEntry" } } }, "LoyaltyRewardVoidEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyRewardVoidResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyAppendEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyAppendResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyStampTokenResult": { "type": "object", "additionalProperties": false, "required": [ "stampToken" ], "properties": { "stampToken": { "$ref": "#/components/schemas/LoyaltyStampToken" } } }, "LoyaltyStampTokenEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyStampTokenResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerLoyaltyTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "plan" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 320 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] } } }, "CustomerLoyaltyProgrammeWallet": { "type": "object", "additionalProperties": false, "required": [ "balance", "lifetimeEarned", "lifetimeRedeemed", "progress", "stampsRemaining", "canIssueReward" ], "properties": { "balance": { "type": "integer", "minimum": 0 }, "lifetimeEarned": { "type": "integer", "minimum": 0 }, "lifetimeRedeemed": { "type": "integer", "minimum": 0 }, "progress": { "type": "number", "minimum": 0, "maximum": 1 }, "stampsRemaining": { "type": "integer", "minimum": 0 }, "canIssueReward": { "type": "boolean" } } }, "CustomerLoyaltyRule": { "type": "object", "additionalProperties": false, "required": [ "id", "trigger", "label", "stampsAwarded" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "trigger": { "type": "string", "enum": [ "booking_completed", "ticket_redeemed", "manual", "coupon_redeemed" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "stampsAwarded": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "CustomerLoyaltyReward": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "description", "redemptionTokenHint", "issuedAt", "redeemedAt", "voidedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "issued", "redeemed", "voided" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "redemptionTokenHint": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "issuedAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "voidedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" }, "program": { "$ref": "#/components/schemas/LoyaltyRewardProgramSummary" } } }, "CustomerLoyaltyLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "delta", "balanceAfter", "sourceType", "note", "occurredAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "earn", "adjustment", "reward_redemption", "reversal" ] }, "delta": { "type": "integer", "minimum": -1000000000, "maximum": 1000000000 }, "balanceAfter": { "type": "integer", "minimum": 0 }, "sourceType": { "type": "string", "minLength": 1, "maxLength": 160 }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" } } }, "CustomerLoyaltyProgramme": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "rewardDescription", "requiredStamps", "status", "validFrom", "validUntil", "activeNow", "wallet", "rules", "rewards", "entries", "progression" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "rewardDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "requiredStamps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "activeNow": { "type": "boolean" }, "wallet": { "$ref": "#/components/schemas/CustomerLoyaltyProgrammeWallet" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyRule" }, "maxItems": 25 }, "rewards": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyReward" }, "maxItems": 100 }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyLedgerEntry" }, "maxItems": 100 }, "progression": { "$ref": "#/components/schemas/CustomerLoyaltyProgression" } } }, "CustomerLoyaltyWallet": { "type": "object", "additionalProperties": false, "required": [ "tenant", "customer", "programmes" ], "properties": { "tenant": { "$ref": "#/components/schemas/CustomerLoyaltyTenant" }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" }, "programmes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyProgramme" }, "maxItems": 100 } } }, "CustomerLoyaltyWalletResult": { "type": "object", "additionalProperties": false, "required": [ "loyalty" ], "properties": { "loyalty": { "$ref": "#/components/schemas/CustomerLoyaltyWallet" } } }, "CustomerLoyaltyWalletEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerLoyaltyWalletResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerLoyaltyAppendResult": { "type": "object", "additionalProperties": false, "required": [ "loyalty" ], "properties": { "loyalty": { "$ref": "#/components/schemas/LoyaltyAppendResult" } } }, "CustomerLoyaltyAppendEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerLoyaltyAppendResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerLoyaltyRewardIssueResult": { "type": "object", "additionalProperties": false, "required": [ "loyalty" ], "properties": { "loyalty": { "$ref": "#/components/schemas/LoyaltyRewardIssueResult" } } }, "CustomerLoyaltyRewardIssueEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerLoyaltyRewardIssueResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "title", "kind" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "percentage", "fixedAmount", "bogo", "custom" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$" }, "amountOffMinor": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "percentOffBasisPoints": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "buyQuantity": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "getQuantity": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "customBenefit": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "terms": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 20000 }, { "type": "null" } ] }, "dailyLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "totalLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CouponUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "percentage", "fixedAmount", "bogo", "custom" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$" }, "amountOffMinor": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "percentOffBasisPoints": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "buyQuantity": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "getQuantity": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ] }, "customBenefit": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "terms": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 20000 }, { "type": "null" } ] }, "dailyLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "totalLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "minProperties": 1 }, "CouponRedemptionInput": { "type": "object", "additionalProperties": false, "properties": { "customerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] } } }, "CouponScanInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 256 }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] } } }, "CouponRedemptionVoidInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "CouponOfflineIssueInput": { "type": "object", "additionalProperties": false, "required": [ "count" ], "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 500 }, "deviceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "CouponOfflineSyncItem": { "type": "object", "additionalProperties": false, "required": [ "code", "signature", "redeemedAt", "eventId" ], "properties": { "code": { "type": "string", "minLength": 16, "maxLength": 128 }, "signature": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$", "minLength": 64, "maxLength": 64 }, "deviceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "redeemedAt": { "type": "string", "format": "date-time" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "CouponOfflineSyncInput": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CouponOfflineSyncItem" }, "maxItems": 500, "minItems": 1 } } }, "CouponListQuery": { "type": "object", "additionalProperties": false, "properties": { "includeEnded": { "type": "boolean", "default": false } } }, "CouponRedemptionQuery": { "type": "object", "additionalProperties": false, "properties": { "couponId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "redeemed", "voided" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } } }, "CouponVoucherBatchQuery": { "type": "object", "additionalProperties": false, "properties": { "couponId": { "type": "string", "minLength": 1, "maxLength": 160 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } } }, "CouponLocation": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "CouponBenefitPercentage": { "type": "object", "additionalProperties": false, "required": [ "kind", "percentOffBasisPoints" ], "properties": { "kind": { "type": "string", "const": "percentage" }, "percentOffBasisPoints": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "CouponBenefitFixedAmount": { "type": "object", "additionalProperties": false, "required": [ "kind", "amountOffMinor", "currency" ], "properties": { "kind": { "type": "string", "const": "fixed_amount" }, "amountOffMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Za-z]{3}$" } } }, "CouponBenefitBogo": { "type": "object", "additionalProperties": false, "required": [ "kind", "buyQuantity", "getQuantity" ], "properties": { "kind": { "type": "string", "const": "bogo" }, "buyQuantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "getQuantity": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "CouponBenefitCustom": { "type": "object", "additionalProperties": false, "required": [ "kind", "description" ], "properties": { "kind": { "type": "string", "const": "custom" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "CouponBenefit": { "oneOf": [ { "$ref": "#/components/schemas/CouponBenefitPercentage" }, { "$ref": "#/components/schemas/CouponBenefitFixedAmount" }, { "$ref": "#/components/schemas/CouponBenefitBogo" }, { "$ref": "#/components/schemas/CouponBenefitCustom" } ], "discriminator": { "propertyName": "kind" } }, "CouponMetrics": { "type": "object", "additionalProperties": false, "required": [ "redeemedToday", "redeemedTotal", "reservedToday", "reservedTotal", "pendingClaims", "remainingToday", "remainingTotal" ], "properties": { "redeemedToday": { "type": "integer", "minimum": 0 }, "redeemedTotal": { "type": "integer", "minimum": 0 }, "reservedToday": { "type": "integer", "minimum": 0 }, "reservedTotal": { "type": "integer", "minimum": 0 }, "pendingClaims": { "type": "integer", "minimum": 0 }, "remainingToday": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "remainingTotal": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } } }, "Coupon": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "location", "title", "description", "benefit", "terms", "dailyLimit", "totalLimit", "status", "activeNow", "validFrom", "validUntil", "activatedAt", "pausedAt", "endedAt", "createdAt", "updatedAt", "metrics" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "location": { "$ref": "#/components/schemas/CouponLocation" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "benefit": { "$ref": "#/components/schemas/CouponBenefit" }, "terms": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 20000 }, { "type": "null" } ] }, "dailyLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "totalLimit": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "activeNow": { "type": "boolean" }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "activatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "pausedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metrics": { "$ref": "#/components/schemas/CouponMetrics" } } }, "CouponClaim": { "type": "object", "additionalProperties": false, "required": [ "id", "couponId", "customerId", "status", "scanTokenHint", "scanTokenExpiresAt", "claimedAt", "redeemedAt", "cancelledAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "couponId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "redeemed", "cancelled", "expired" ] }, "scanTokenHint": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "scanTokenExpiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "claimedAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "coupon": { "$ref": "#/components/schemas/CouponClaimCouponSummary" } } }, "CouponRedemption": { "type": "object", "additionalProperties": false, "required": [ "id", "couponId", "customerId", "claimId", "offlineVoucherId", "source", "status", "quantity", "redeemedAt", "note", "voidedAt", "voidReason" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "couponId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "claimId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "offlineVoucherId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "customer_scan", "operator", "offline_voucher" ] }, "status": { "type": "string", "enum": [ "redeemed", "voided" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "redeemedAt": { "type": "string", "format": "date-time" }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "voidedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "voidReason": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "coupon": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyCustomerSummary" }, { "type": "null" } ] } } }, "CouponRedemptionLoyaltyResult": { "type": "object", "additionalProperties": false, "required": [ "status", "appended", "deduplicated" ], "properties": { "status": { "type": "string", "enum": [ "applied", "not_applicable", "pending" ] }, "appended": { "type": "integer", "minimum": 0 }, "deduplicated": { "type": "integer", "minimum": 0 } } }, "CouponRedemptionResult": { "type": "object", "additionalProperties": false, "required": [ "redemption", "deduplicated", "loyalty" ], "properties": { "redemption": { "$ref": "#/components/schemas/CouponRedemption" }, "deduplicated": { "type": "boolean" }, "loyalty": { "$ref": "#/components/schemas/CouponRedemptionLoyaltyResult" } } }, "CouponClaimResult": { "type": "object", "additionalProperties": false, "required": [ "claim", "scanToken", "deduplicated" ], "properties": { "claim": { "$ref": "#/components/schemas/CouponClaim" }, "scanToken": { "oneOf": [ { "type": "string", "minLength": 16, "maxLength": 256 }, { "type": "null" } ] }, "deduplicated": { "type": "boolean" } } }, "CouponVoucherBatch": { "type": "object", "additionalProperties": false, "required": [ "id", "couponId", "deviceId", "requestedCount", "issuedCount", "expiresAt", "createdAt", "redeemedCount" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "couponId": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 500 }, "issuedCount": { "type": "integer", "minimum": 0, "maximum": 500 }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "redeemedCount": { "type": "integer", "minimum": 0, "maximum": 500 } } }, "CouponOfflineVoucher": { "type": "object", "additionalProperties": false, "required": [ "id", "sequenceNumber", "codeHint", "deviceId", "issuedAt", "expiresAt", "redeemedAt", "code", "signature" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "sequenceNumber": { "type": "integer", "minimum": 1, "maximum": 500 }, "codeHint": { "type": "string", "minLength": 1, "maxLength": 160 }, "deviceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "issuedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "code": { "oneOf": [ { "type": "string", "minLength": 16, "maxLength": 128 }, { "type": "null" } ] }, "signature": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$", "minLength": 64, "maxLength": 64 } } }, "CouponOfflineIssueResult": { "type": "object", "additionalProperties": false, "required": [ "batch", "vouchers", "deduplicated" ], "properties": { "batch": { "$ref": "#/components/schemas/CouponVoucherBatch" }, "vouchers": { "type": "array", "items": { "$ref": "#/components/schemas/CouponOfflineVoucher" }, "maxItems": 500 }, "deduplicated": { "type": "boolean" } } }, "CouponOfflineSyncEntry": { "type": "object", "additionalProperties": false, "required": [ "eventId", "status" ], "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "applied", "deduplicated", "conflict" ] }, "redemption": { "$ref": "#/components/schemas/CouponRedemption" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "CouponOfflineSyncResult": { "type": "object", "additionalProperties": false, "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CouponOfflineSyncEntry" }, "maxItems": 500 } } }, "CustomerCouponTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "CustomerCouponCenter": { "type": "object", "additionalProperties": false, "required": [ "tenant", "customer", "available", "claims", "redemptions" ], "properties": { "tenant": { "$ref": "#/components/schemas/CustomerCouponTenant" }, "customer": { "$ref": "#/components/schemas/LoyaltyCustomerSummary" }, "available": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" }, "maxItems": 500 }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/CouponClaim" }, "maxItems": 500 }, "redemptions": { "type": "array", "items": { "$ref": "#/components/schemas/CouponRedemption" }, "maxItems": 500 } } }, "CouponResult": { "type": "object", "additionalProperties": false, "required": [ "coupon" ], "properties": { "coupon": { "$ref": "#/components/schemas/Coupon" } } }, "CouponEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponListResult": { "type": "object", "additionalProperties": false, "required": [ "coupons" ], "properties": { "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" }, "maxItems": 500 } } }, "CouponListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponRedemptionListResult": { "type": "object", "additionalProperties": false, "required": [ "redemptions" ], "properties": { "redemptions": { "type": "array", "items": { "$ref": "#/components/schemas/CouponRedemption" }, "maxItems": 500 } } }, "CouponRedemptionListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponRedemptionListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponRedemptionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponRedemptionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponVoucherBatchListResult": { "type": "object", "additionalProperties": false, "required": [ "batches" ], "properties": { "batches": { "type": "array", "items": { "$ref": "#/components/schemas/CouponVoucherBatch" }, "maxItems": 500 } } }, "CouponVoucherBatchListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponVoucherBatchListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponOfflineIssueEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponOfflineIssueResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponOfflineSyncEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CouponOfflineSyncResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerCouponCenterResult": { "type": "object", "additionalProperties": false, "required": [ "coupons" ], "properties": { "coupons": { "$ref": "#/components/schemas/CustomerCouponCenter" } } }, "CustomerCouponCenterEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerCouponCenterResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerCouponClaimResult": { "type": "object", "additionalProperties": false, "required": [ "coupon" ], "properties": { "coupon": { "$ref": "#/components/schemas/CouponClaimResult" } } }, "CustomerCouponClaimEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerCouponClaimResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerCouponCancelValue": { "type": "object", "additionalProperties": false, "required": [ "claim" ], "properties": { "claim": { "$ref": "#/components/schemas/CouponClaim" } } }, "CustomerCouponCancelResult": { "type": "object", "additionalProperties": false, "required": [ "coupon" ], "properties": { "coupon": { "$ref": "#/components/schemas/CustomerCouponCancelValue" } } }, "CustomerCouponCancelEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerCouponCancelResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicCouponCatalog": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "location", "coupons" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "location": { "$ref": "#/components/schemas/Location" }, "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" }, "maxItems": 500 } } }, "PublicCouponCatalogEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicCouponCatalog" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CouponClaimCouponSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "benefit", "validUntil", "location" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "benefit": { "$ref": "#/components/schemas/CouponBenefit" }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "location": { "$ref": "#/components/schemas/CouponLocation" } } }, "TicketPromotionItemInput": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "role", "minimumQuantity" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "required", "discounted" ] }, "minimumQuantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maximumQuantity": { "type": "integer", "minimum": 1, "maximum": 10000 } } }, "TicketPromotionWriteInput": { "type": "object", "additionalProperties": false, "required": [ "offeringId", "name", "publicLabel", "kind", "discountType" ], "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "publicLabel": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 0, "maxLength": 500 }, "kind": { "type": "string", "enum": [ "code", "limitedTime", "bundle", "crossSell" ] }, "discountType": { "type": "string", "enum": [ "percentage", "fixedAmount", "bundlePrice" ] }, "percentageOffBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountOff": { "type": "integer", "minimum": 1 }, "bundlePrice": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "minimumAmount": { "type": "integer", "minimum": 1 }, "maxTotalRedemptions": { "type": "integer", "minimum": 1 }, "maxPerCustomer": { "type": "integer", "minimum": 1 }, "assignment": { "type": "string", "enum": [ "open", "invitationOnly" ], "default": "open" }, "code": { "type": "string", "minLength": 4, "maxLength": 40 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "displayOnPurchasePage": { "type": "boolean", "default": false }, "priority": { "type": "integer", "minimum": -1000, "maximum": 1000, "default": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionItemInput" }, "maxItems": 100, "default": [] } } }, "TicketPromotionInvitationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "expiresAt": { "type": "string", "format": "date-time" }, "sendNow": { "type": "boolean", "default": true } } }, "TicketPromotionInvitationImportInput": { "type": "object", "additionalProperties": false, "required": [ "fileName", "emails" ], "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "emails": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 500 }, "maxItems": 5000, "minItems": 1 } } }, "PublicTicketPromotionQuoteInput": { "oneOf": [ { "$ref": "#/components/schemas/PublicTicketPromotionCodeQuoteInput" }, { "$ref": "#/components/schemas/PublicTicketPromotionIdQuoteInput" }, { "$ref": "#/components/schemas/PublicTicketPromotionInvitationQuoteInput" } ] }, "TicketPromotionItem": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketTypeId", "role", "minimumQuantity", "maximumQuantity", "sortOrder" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "required", "discounted" ] }, "minimumQuantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maximumQuantity": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 99 } } }, "TicketPromotionCounts": { "type": "object", "additionalProperties": false, "required": [ "invitations", "quotes", "redemptions" ], "properties": { "invitations": { "type": "integer", "minimum": 0 }, "quotes": { "type": "integer", "minimum": 0 }, "redemptions": { "type": "integer", "minimum": 0 } } }, "TicketPromotion": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "name", "publicLabel", "description", "kind", "status", "discountType", "percentageOffBps", "amountOff", "bundlePrice", "currency", "minimumAmount", "maxTotalRedemptions", "maxPerCustomer", "assignment", "hasCode", "codeHint", "startsAt", "endsAt", "displayOnPurchasePage", "priority", "items", "counts", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "publicLabel": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "code", "limitedTime", "bundle", "crossSell" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "discountType": { "type": "string", "enum": [ "percentage", "fixedAmount", "bundlePrice" ] }, "percentageOffBps": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "amountOff": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "bundlePrice": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "minimumAmount": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "maxTotalRedemptions": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "maxPerCustomer": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "assignment": { "type": "string", "enum": [ "open", "invitationOnly" ] }, "hasCode": { "type": "boolean" }, "codeHint": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "startsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "displayOnPurchasePage": { "type": "boolean" }, "priority": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionItem" }, "maxItems": 100 }, "counts": { "$ref": "#/components/schemas/TicketPromotionCounts" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TicketPromotionMutationResult": { "type": "object", "additionalProperties": false, "required": [ "promotion" ], "properties": { "promotion": { "$ref": "#/components/schemas/TicketPromotion" }, "createdCode": { "type": "string", "minLength": 4, "maxLength": 40 }, "rotatedCode": { "type": "string", "minLength": 4, "maxLength": 40 } } }, "TicketPromotionListResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "items" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-promotion-contract-v1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotion" }, "maxItems": 200 } } }, "TicketPromotionInvitation": { "type": "object", "additionalProperties": false, "required": [ "id", "promotionId", "emailMasked", "status", "expiresAt", "lastSentAt", "nextReminderAt", "remindersSent", "reservedAt", "redeemedAt", "cancelledAt", "failureReason", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMasked": { "type": "string", "minLength": 3, "maxLength": 320 }, "status": { "type": "string", "enum": [ "pending", "queued", "sent", "failed", "reserved", "redeemed", "cancelled", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "lastSentAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "nextReminderAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "remindersSent": { "type": "integer", "minimum": 0, "maximum": 2 }, "reservedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "redeemedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failureReason": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TicketPromotionInvitationListResult": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionInvitation" }, "maxItems": 500 } } }, "TicketPromotionInvitationDelivery": { "type": "object", "additionalProperties": false, "required": [ "invitation", "emailMessageId", "queued" ], "properties": { "invitation": { "$ref": "#/components/schemas/TicketPromotionInvitation" }, "emailMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "queued": { "type": "boolean", "const": true } } }, "TicketPromotionInvitationCreateResult": { "type": "object", "additionalProperties": false, "required": [ "invitation", "invitationToken" ], "properties": { "invitation": { "$ref": "#/components/schemas/TicketPromotionInvitation" }, "invitationToken": { "type": "string", "minLength": 40, "maxLength": 160 }, "delivery": { "$ref": "#/components/schemas/TicketPromotionInvitationDelivery" } } }, "TicketPromotionInvitationResendResult": { "type": "object", "additionalProperties": false, "required": [ "invitation", "emailMessageId", "queued" ], "properties": { "invitation": { "$ref": "#/components/schemas/TicketPromotionInvitation" }, "emailMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "queued": { "type": "boolean", "const": true } } }, "TicketPromotionImportError": { "type": "object", "additionalProperties": false, "required": [ "row", "reason" ], "properties": { "row": { "type": "integer", "minimum": 1, "maximum": 5000 }, "reason": { "type": "string", "enum": [ "duplicateInImport", "invalidEmail", "alreadyInvited" ] } } }, "TicketPromotionInvitationImport": { "type": "object", "additionalProperties": false, "required": [ "id", "promotionId", "fileName", "status", "totalRows", "acceptedRows", "rejectedRows", "errorReport", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "processing", "completed", "partial_failed", "failed" ] }, "totalRows": { "type": "integer", "minimum": 1, "maximum": 5000 }, "acceptedRows": { "type": "integer", "minimum": 0, "maximum": 5000 }, "rejectedRows": { "type": "integer", "minimum": 0, "maximum": 5000 }, "errorReport": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionImportError" }, "maxItems": 5000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TicketPromotionInvitationImportListResult": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionInvitationImport" }, "maxItems": 100 } } }, "PublicVisibleTicketPromotion": { "type": "object", "additionalProperties": false, "required": [ "id", "publicLabel", "description", "kind", "discountType", "percentageOffBps", "amountOff", "bundlePrice", "currency", "minimumAmount", "startsAt", "endsAt", "items" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "publicLabel": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "limitedTime", "bundle", "crossSell" ] }, "discountType": { "type": "string", "enum": [ "percentage", "fixedAmount", "bundlePrice" ] }, "percentageOffBps": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "amountOff": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "bundlePrice": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "minimumAmount": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "startsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPromotionItem" }, "maxItems": 100 } } }, "PublicTicketPromotionListResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "promotions" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-promotion-contract-v1" }, "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/PublicVisibleTicketPromotion" }, "maxItems": 200 } } }, "PublicTicketPromotionQuoteLine": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "quantity", "unitAmount", "grossAmount", "discountAmount", "netAmount" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unitAmount": { "type": "integer", "minimum": 0 }, "grossAmount": { "type": "integer", "minimum": 0 }, "discountAmount": { "type": "integer", "minimum": 0 }, "netAmount": { "type": "integer", "minimum": 0 } } }, "PublicTicketPromotionQuote": { "type": "object", "additionalProperties": false, "required": [ "id", "token", "promotionId", "publicLabel", "offeringId", "currency", "subtotalAmount", "discountAmount", "totalAmount", "lines", "expiresAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "token": { "type": "string", "minLength": 32, "maxLength": 256 }, "promotionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "publicLabel": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "subtotalAmount": { "type": "integer", "minimum": 0 }, "discountAmount": { "type": "integer", "minimum": 0 }, "totalAmount": { "type": "integer", "minimum": 0 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketPromotionQuoteLine" }, "maxItems": 100, "minItems": 1 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PublicTicketPromotionQuoteResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "quote", "replayed" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-promotion-contract-v1" }, "quote": { "$ref": "#/components/schemas/PublicTicketPromotionQuote" }, "replayed": { "type": "boolean" } } }, "TicketPromotionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotion" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionMutationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitation" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitationListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitationCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationResendEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitationResendResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationImportEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitationImport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketPromotionInvitationImportListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketPromotionInvitationImportListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketPromotionListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketPromotionListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketPromotionQuoteEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketPromotionQuoteResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketPromotionCodeQuoteInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "buyerEmail", "items", "clientRequestId", "code" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "seatHoldToken": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItemInput" }, "minItems": 1 }, "clientRequestId": { "type": "string", "minLength": 8, "maxLength": 128 }, "code": { "type": "string", "minLength": 4, "maxLength": 40 } } }, "PublicTicketPromotionIdQuoteInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "buyerEmail", "items", "clientRequestId", "promotionId" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "seatHoldToken": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItemInput" }, "minItems": 1 }, "clientRequestId": { "type": "string", "minLength": 8, "maxLength": 128 }, "promotionId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "PublicTicketPromotionInvitationQuoteInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "buyerEmail", "items", "clientRequestId", "invitationToken" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "buyerEmail": { "type": "string", "format": "email", "maxLength": 320 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "default": "EUR" }, "seatHoldToken": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrderItemInput" }, "minItems": 1 }, "clientRequestId": { "type": "string", "minLength": 8, "maxLength": 128 }, "invitationToken": { "type": "string", "minLength": 40, "maxLength": 160 } } }, "TicketQueueOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "status", "saleStartsAt", "saleEndsAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 2, "maxLength": 220 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "saleStartsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "saleEndsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TicketQueueMetrics": { "type": "object", "additionalProperties": false, "required": [ "totalEnqueued", "totalAdmitted", "totalCompleted", "totalTimedOut", "totalExited" ], "properties": { "totalEnqueued": { "type": "integer", "minimum": 0 }, "totalAdmitted": { "type": "integer", "minimum": 0 }, "totalCompleted": { "type": "integer", "minimum": 0 }, "totalTimedOut": { "type": "integer", "minimum": 0 }, "totalExited": { "type": "integer", "minimum": 0 } } }, "TicketQueue": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "offeringId", "offering", "enabled", "autoActivationEnabled", "loadThreshold", "graceTimeoutSeconds", "lotteryDurationSeconds", "maxConcurrentCheckouts", "maxQueueSize", "status", "activatedAt", "pausedAt", "endedAt", "metrics", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offering": { "$ref": "#/components/schemas/TicketQueueOffering" }, "enabled": { "type": "boolean" }, "autoActivationEnabled": { "type": "boolean" }, "loadThreshold": { "type": "integer", "minimum": 5, "maximum": 100000 }, "graceTimeoutSeconds": { "type": "integer", "minimum": 60, "maximum": 1800 }, "lotteryDurationSeconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "maxConcurrentCheckouts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "maxQueueSize": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "inactive", "active", "paused", "ended" ] }, "activatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "pausedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "metrics": { "$ref": "#/components/schemas/TicketQueueMetrics" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TicketQueueEntryCounts": { "type": "object", "additionalProperties": false, "required": [ "waiting", "admitted", "checkoutActive", "completed", "timedOut", "exited", "removed" ], "properties": { "waiting": { "type": "integer", "minimum": 0 }, "admitted": { "type": "integer", "minimum": 0 }, "checkoutActive": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "timedOut": { "type": "integer", "minimum": 0 }, "exited": { "type": "integer", "minimum": 0 }, "removed": { "type": "integer", "minimum": 0 } } }, "TicketQueueRecentEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "sequence", "status", "emailMasked", "enteredAt", "admittedAt", "checkoutExpiresAt", "checkoutStartedAt", "completedAt", "timedOutAt", "exitedAt", "removedAt", "lastSeenAt", "orderId" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "sequence": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "waiting", "admitted", "checkoutActive", "completed", "timedOut", "exited", "removed" ] }, "emailMasked": { "oneOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "type": "null" } ] }, "enteredAt": { "type": "string", "format": "date-time" }, "admittedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkoutExpiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkoutStartedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "timedOutAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "exitedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "removedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "orderId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } } }, "TicketQueueEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "entryId", "kind", "actorUserId", "details", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "entryId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "CONFIGURED", "ACTIVATED", "AUTO_ACTIVATED", "PAUSED", "RESUMED", "ENDED", "JOINED", "ADMITTED", "CHECKOUT_STARTED", "COMPLETED", "TIMED_OUT", "EXITED", "REMOVED" ] }, "actorUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "details": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "TicketQueueOperatorWorkspace": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "queue", "counts", "recentEntries", "recentEvents" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-queue-contract-v1" }, "queue": { "oneOf": [ { "$ref": "#/components/schemas/TicketQueue" }, { "type": "null" } ] }, "counts": { "$ref": "#/components/schemas/TicketQueueEntryCounts" }, "recentEntries": { "type": "array", "items": { "$ref": "#/components/schemas/TicketQueueRecentEntry" }, "maxItems": 30 }, "recentEvents": { "type": "array", "items": { "$ref": "#/components/schemas/TicketQueueEvent" }, "maxItems": 50 } } }, "TicketQueuePublicState": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "offeringId", "enabled", "status", "isAdmissionRequired", "waitingCount", "activeCheckoutCount", "estimatedWaitSeconds" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-queue-contract-v1" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "inactive", "active", "paused", "ended" ] }, "isAdmissionRequired": { "type": "boolean" }, "waitingCount": { "type": "integer", "minimum": 0 }, "activeCheckoutCount": { "type": "integer", "minimum": 0 }, "estimatedWaitSeconds": { "type": "integer", "minimum": 0 } } }, "TicketQueueEntryPublicState": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "entryId", "offeringId", "status", "position", "queueSize", "activeCheckoutCount", "estimatedWaitSeconds", "checkoutExpiresAt" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-queue-contract-v1" }, "entryId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "waiting", "admitted", "checkoutActive", "completed", "timedOut", "exited", "removed" ] }, "position": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "queueSize": { "type": "integer", "minimum": 0 }, "activeCheckoutCount": { "type": "integer", "minimum": 0 }, "estimatedWaitSeconds": { "type": "integer", "minimum": 0 }, "checkoutExpiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "PublicTicketQueueJoinResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "sessionToken", "restored", "entry" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-queue-contract-v1" }, "sessionToken": { "type": "string", "pattern": "^tq_[0-9a-f]{64}$", "writeOnly": true }, "restored": { "type": "boolean" }, "entry": { "$ref": "#/components/schemas/TicketQueueEntryPublicState" } } }, "PublicTicketQueueExitResult": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "unchanged" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "waiting", "admitted", "checkoutActive", "completed", "timedOut", "exited", "removed" ] }, "unchanged": { "type": "boolean" } } }, "TicketQueueRemoveEntryResult": { "type": "object", "additionalProperties": false, "required": [ "id", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "waiting", "admitted", "checkoutActive", "completed", "timedOut", "exited", "removed" ] } } }, "TicketQueueOperatorWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketQueueOperatorWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketQueuePublicStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketQueuePublicState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketQueueEntryPublicStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketQueueEntryPublicState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketQueueJoinEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketQueueJoinResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketQueueExitEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketQueueExitResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketQueueRemoveEntryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketQueueRemoveEntryResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketQueueStateInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "TicketRefundAmountSelectionInput": { "type": "object", "additionalProperties": false, "required": [ "scope", "amountMinor" ], "properties": { "scope": { "type": "string", "const": "amount" }, "amountMinor": { "type": "integer", "minimum": 1 } } }, "TicketRefundTicketsSelectionInput": { "type": "object", "additionalProperties": false, "required": [ "scope", "ticketIds" ], "properties": { "scope": { "type": "string", "const": "tickets" }, "ticketIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 1, "maxItems": 500 } } }, "TicketRefundFullOrderSelectionInput": { "type": "object", "additionalProperties": false, "required": [ "scope" ], "properties": { "scope": { "type": "string", "const": "fullOrder" } } }, "TicketRefundSelectionInput": { "oneOf": [ { "$ref": "#/components/schemas/TicketRefundAmountSelectionInput" }, { "$ref": "#/components/schemas/TicketRefundTicketsSelectionInput" }, { "$ref": "#/components/schemas/TicketRefundFullOrderSelectionInput" } ], "discriminator": { "propertyName": "scope" } }, "TicketRefundPreviewInput": { "type": "object", "additionalProperties": false, "required": [ "orderId", "selection" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "selection": { "$ref": "#/components/schemas/TicketRefundSelectionInput" } } }, "TicketRefundCreateInput": { "type": "object", "additionalProperties": false, "required": [ "orderId", "selection", "reason" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "selection": { "$ref": "#/components/schemas/TicketRefundSelectionInput" }, "reason": { "type": "string", "enum": [ "customerRequest", "duplicate", "fraudulent", "eventCancelled", "operatorDecision", "other" ] }, "note": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "TicketRefundBatchPreviewInput": { "type": "object", "additionalProperties": false, "required": [ "offeringId" ], "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketRefundBatchCreateInput": { "type": "object", "additionalProperties": false, "required": [ "offeringId", "reason" ], "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "enum": [ "customerRequest", "duplicate", "fraudulent", "eventCancelled", "operatorDecision", "other" ] }, "note": { "type": "string", "minLength": 0, "maxLength": 500 } } }, "TicketDisputeAcknowledgeInput": { "type": "object", "additionalProperties": false, "required": [ "note" ], "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "TicketRefundAllocation": { "type": "object", "additionalProperties": false, "required": [ "ticketId", "orderItemId", "amountMinor", "releaseTicket" ], "properties": { "ticketId": { "type": "string", "minLength": 1, "maxLength": 160 }, "orderItemId": { "type": "string", "minLength": 1, "maxLength": 160 }, "amountMinor": { "type": "integer", "minimum": 0 }, "releaseTicket": { "type": "boolean" } } }, "TicketRefund": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "orderId", "offeringId", "batchId", "scope", "reason", "status", "amountMinor", "currency", "providerStatus", "providerFailureCode", "allocationCount", "allocations", "createdAt", "updatedAt", "succeededAt", "failedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "batchId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "amount", "tickets", "fullOrder", "event" ] }, "reason": { "type": "string", "enum": [ "customerRequest", "duplicate", "fraudulent", "eventCancelled", "operatorDecision", "other" ] }, "status": { "type": "string", "enum": [ "requested", "processing", "succeeded", "failed", "cancelled", "requiresAction" ] }, "amountMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "providerStatus": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "providerFailureCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "allocationCount": { "type": "integer", "minimum": 0 }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/TicketRefundAllocation" }, "maxItems": 500 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "succeededAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TicketRefundPreview": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "orderId", "scope", "amountMinor", "currency", "remainingRefundableBeforeMinor", "remainingRefundableAfterMinor", "completesOrderRefund", "allocations", "excludedRedeemedTicketCount" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-finance-contract-v1" }, "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "type": "string", "enum": [ "amount", "tickets", "fullOrder", "event" ] }, "amountMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "remainingRefundableBeforeMinor": { "type": "integer", "minimum": 1 }, "remainingRefundableAfterMinor": { "type": "integer", "minimum": 0 }, "completesOrderRefund": { "type": "boolean" }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/TicketRefundAllocation" }, "maxItems": 500 }, "excludedRedeemedTicketCount": { "type": "integer", "minimum": 0 } } }, "TicketRefundListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "hasMore", "limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketRefund" }, "maxItems": 100 }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "TicketRefundMutationResult": { "type": "object", "additionalProperties": false, "required": [ "refund", "idempotent" ], "properties": { "refund": { "$ref": "#/components/schemas/TicketRefund" }, "idempotent": { "type": "boolean" } } }, "TicketRefundBatchOffering": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "currency" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" } } }, "TicketRefundBatchPreviewItem": { "type": "object", "additionalProperties": false, "required": [ "orderId", "amountMinor", "currency", "paymentReady", "releasedTicketCount", "excludedRedeemedTicketCount" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "amountMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "paymentReady": { "type": "boolean" }, "releasedTicketCount": { "type": "integer", "minimum": 0 }, "excludedRedeemedTicketCount": { "type": "integer", "minimum": 0 } } }, "TicketRefundBatchPreview": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "offering", "orderCount", "amountMinor", "paymentBlockedOrderCount", "disputeBlockedOrderCount", "items" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ticket-refund-batch-preview-v1" }, "offering": { "$ref": "#/components/schemas/TicketRefundBatchOffering" }, "orderCount": { "type": "integer", "minimum": 0 }, "amountMinor": { "type": "integer", "minimum": 0 }, "paymentBlockedOrderCount": { "type": "integer", "minimum": 0 }, "disputeBlockedOrderCount": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketRefundBatchPreviewItem" } } } }, "TicketRefundBatchOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "orderId", "refundId", "status", "amountMinor", "failureCode", "processedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "refundId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed", "skipped" ] }, "amountMinor": { "type": "integer", "minimum": 0 }, "failureCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "processedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "TicketRefundBatch": { "type": "object", "additionalProperties": false, "required": [ "id", "offeringId", "status", "reason", "note", "plannedOrderCount", "plannedAmountMinor", "processedOrderCount", "successfulOrderCount", "failedOrderCount", "orders", "queuedAt", "completedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "preparing", "queued", "processing", "completed", "partiallyFailed", "failed", "cancelled" ] }, "reason": { "type": "string", "enum": [ "customerRequest", "duplicate", "fraudulent", "eventCancelled", "operatorDecision", "other" ] }, "note": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "plannedOrderCount": { "type": "integer", "minimum": 0 }, "plannedAmountMinor": { "type": "integer", "minimum": 0 }, "processedOrderCount": { "type": "integer", "minimum": 0 }, "successfulOrderCount": { "type": "integer", "minimum": 0 }, "failedOrderCount": { "type": "integer", "minimum": 0 }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/TicketRefundBatchOrder" } }, "queuedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TicketRefundBatchMutationResult": { "type": "object", "additionalProperties": false, "required": [ "batch", "idempotent" ], "properties": { "batch": { "$ref": "#/components/schemas/TicketRefundBatch" }, "idempotent": { "type": "boolean" } } }, "TicketDispute": { "type": "object", "additionalProperties": false, "required": [ "id", "orderId", "offeringId", "providerStatus", "providerReason", "state", "amountMinor", "currency", "evidenceDueAt", "resolutionNote", "openedAt", "resolvedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "providerStatus": { "type": "string", "minLength": 1, "maxLength": 80 }, "providerReason": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "open", "underReview", "won", "lost" ] }, "amountMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "evidenceDueAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "resolutionNote": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "openedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TicketDisputeListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "hasMore", "limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketDispute" }, "maxItems": 100 }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "TicketRefundEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefund" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundMutationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundBatchPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundBatchPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundBatchEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundBatch" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketRefundBatchMutationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketRefundBatchMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketDisputeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketDispute" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketDisputeListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketDisputeListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketCheckInInput": { "type": "object", "additionalProperties": false, "properties": { "accessCode": { "type": "string", "minLength": 1, "maxLength": 160 }, "clientEventId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "TicketOfflineScanEntry": { "type": "object", "additionalProperties": false, "required": [ "clientEventId", "ticketDigest", "occurredAt" ], "properties": { "clientEventId": { "type": "string", "format": "uuid" }, "ticketDigest": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "TicketScanListQuery": { "type": "object", "additionalProperties": false, "properties": { "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "origin": { "type": "string", "enum": [ "live", "offline" ] }, "outcome": { "type": "string", "enum": [ "accepted", "alreadyRedeemed", "invalidCode", "invalidStatus", "offlinePackageExpired", "offlinePackageRevoked", "wrongEvent" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } }, "TicketCheckInCommandResult": { "type": "object", "additionalProperties": false, "required": [ "idempotent", "scan" ], "properties": { "idempotent": { "type": "boolean" }, "scan": { "$ref": "#/components/schemas/TicketScanRecord" }, "ticket": { "$ref": "#/components/schemas/Ticket" } } }, "TicketScanListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "hasMore", "limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketScanRecord" }, "maxItems": 200 }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } }, "TicketOfflineSyncResult": { "type": "object", "additionalProperties": false, "required": [ "items", "processed" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TicketCheckInCommandResult" }, "minItems": 1, "maxItems": 200 }, "processed": { "type": "integer", "minimum": 1, "maximum": 200 } } }, "TicketEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Ticket" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketCheckInCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketCheckInCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketScanListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketScanListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOfflinePackageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOfflinePackage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TicketOfflineSyncEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TicketOfflineSyncResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OfflineOperationsWorkspaceQuery": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 191 } } }, "OfflineDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "deviceKey", "name", "status", "secretVersion", "lastSequence", "lastSyncAt", "lastSeenAt", "revokedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceKey": { "type": "string", "minLength": 24, "maxLength": 128, "pattern": "^odv_[A-Za-z0-9_-]{20,120}$" }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "status": { "type": "string", "enum": [ "active", "stale", "expired", "revoked" ] }, "secretVersion": { "type": "integer", "minimum": 1 }, "lastSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OfflineDeviceCounts": { "type": "object", "additionalProperties": false, "required": [ "ticketPackageItems", "couponVouchers", "creditReservations", "pendingOperations", "conflicts" ], "properties": { "ticketPackageItems": { "type": "integer", "minimum": 0 }, "couponVouchers": { "type": "integer", "minimum": 0 }, "creditReservations": { "type": "integer", "minimum": 0 }, "pendingOperations": { "type": "integer", "minimum": 0 }, "conflicts": { "type": "integer", "minimum": 0 } } }, "OfflineDeviceSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "deviceKey", "name", "status", "secretVersion", "lastSequence", "lastSyncAt", "lastSeenAt", "revokedAt", "createdAt", "updatedAt", "locationName", "counts" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceKey": { "type": "string", "minLength": 24, "maxLength": 128, "pattern": "^odv_[A-Za-z0-9_-]{20,120}$" }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "status": { "type": "string", "enum": [ "active", "stale", "expired", "revoked" ] }, "secretVersion": { "type": "integer", "minimum": 1 }, "lastSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "locationName": { "type": "string", "minLength": 1, "maxLength": 240 }, "counts": { "$ref": "#/components/schemas/OfflineDeviceCounts" } } }, "OfflineOperationsWorkspace": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "devices", "operations" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/OfflineDeviceSummary" }, "maxItems": 100 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OfflineOperationRecord" }, "maxItems": 100 } } }, "OfflineDeviceEnrollment": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "device", "secret", "nextSequence" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "device": { "$ref": "#/components/schemas/OfflineDeviceSummary" }, "secret": { "type": "string", "pattern": "^vsm_od_[A-Za-z0-9_-]{43}$", "writeOnly": true, "description": "Returned once; never persisted or listed in plaintext" }, "nextSequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "OfflineCreditReservation": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "deviceId", "eventId", "customerId", "customerDisplayName", "currency", "reservedMinor", "remainingMinor", "expiresAt", "revokedAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 191 }, "customerDisplayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "reservedMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "remainingMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "OfflineTicketScanPayload": { "type": "object", "additionalProperties": false, "required": [ "packageId", "ticketDigest" ], "properties": { "packageId": { "type": "string", "minLength": 1, "maxLength": 191 }, "ticketDigest": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } } }, "OfflineCouponRedeemPayload": { "type": "object", "additionalProperties": false, "required": [ "code", "signature" ], "properties": { "code": { "type": "string", "minLength": 16, "maxLength": 128 }, "signature": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } } }, "OfflineEventCreditChargePayload": { "type": "object", "additionalProperties": false, "required": [ "reservationId", "amountMinor" ], "properties": { "reservationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 } } }, "OfflineTicketScanEnvelope": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "clientEventId", "deviceKey", "sequence", "kind", "occurredAt", "payload", "signature" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "clientEventId": { "type": "string", "minLength": 8, "maxLength": 96, "pattern": "^[A-Za-z0-9][A-Za-z0-9:_-]{7,95}$" }, "deviceKey": { "type": "string", "minLength": 24, "maxLength": 128, "pattern": "^odv_[A-Za-z0-9_-]{20,120}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "ticketScan" }, "occurredAt": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/OfflineTicketScanPayload" }, "signature": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } } }, "OfflineCouponRedeemEnvelope": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "clientEventId", "deviceKey", "sequence", "kind", "occurredAt", "payload", "signature" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "clientEventId": { "type": "string", "minLength": 8, "maxLength": 96, "pattern": "^[A-Za-z0-9][A-Za-z0-9:_-]{7,95}$" }, "deviceKey": { "type": "string", "minLength": 24, "maxLength": 128, "pattern": "^odv_[A-Za-z0-9_-]{20,120}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "couponRedeem" }, "occurredAt": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/OfflineCouponRedeemPayload" }, "signature": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } } }, "OfflineEventCreditChargeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "clientEventId", "deviceKey", "sequence", "kind", "occurredAt", "payload", "signature" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "clientEventId": { "type": "string", "minLength": 8, "maxLength": 96, "pattern": "^[A-Za-z0-9][A-Za-z0-9:_-]{7,95}$" }, "deviceKey": { "type": "string", "minLength": 24, "maxLength": 128, "pattern": "^odv_[A-Za-z0-9_-]{20,120}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "kind": { "type": "string", "const": "eventCreditCharge" }, "occurredAt": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/OfflineEventCreditChargePayload" }, "signature": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } } }, "OfflineOperationResult": { "type": "object", "additionalProperties": false, "required": [ "clientEventId", "sequence", "kind", "status", "reason", "resourceId", "receivedAt" ], "properties": { "clientEventId": { "type": "string", "minLength": 8, "maxLength": 96, "pattern": "^[A-Za-z0-9][A-Za-z0-9:_-]{7,95}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "kind": { "type": "string", "enum": [ "ticketScan", "couponRedeem", "eventCreditCharge" ] }, "status": { "type": "string", "enum": [ "accepted", "duplicate", "conflict", "rejected", "pendingProvider" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "resourceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time" } } }, "OfflineOperationRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "deviceId", "deviceName", "occurredAt", "details", "clientEventId", "sequence", "kind", "status", "reason", "resourceId", "receivedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deviceName": { "type": "string", "minLength": 2, "maxLength": 120 }, "occurredAt": { "type": "string", "format": "date-time" }, "details": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Sanitized domain metadata without bearer values" }, { "type": "null" } ] }, "clientEventId": { "type": "string", "minLength": 8, "maxLength": 96, "pattern": "^[A-Za-z0-9][A-Za-z0-9:_-]{7,95}$" }, "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "kind": { "type": "string", "enum": [ "ticketScan", "couponRedeem", "eventCreditCharge" ] }, "status": { "type": "string", "enum": [ "accepted", "duplicate", "conflict", "rejected", "pendingProvider" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "resourceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time" } } }, "OfflineOperationsSyncResult": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "processed", "results" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-offline-operations-contract-v1" }, "processed": { "type": "integer", "minimum": 1, "maximum": 200 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OfflineOperationResult" }, "minItems": 1, "maxItems": 200 } } }, "OfflineOperationsWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OfflineOperationsWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OfflineDeviceEnrollmentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OfflineDeviceEnrollment" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OfflineDeviceSummaryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OfflineDeviceSummary" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OfflineCreditReservationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OfflineCreditReservation" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OfflineOperationsSyncEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OfflineOperationsSyncResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "IntegrationCredentialScope": { "type": "string", "enum": [ "public:read", "venues:read", "venues:write", "bookings:read", "bookings:write", "customers:read", "customers:write", "leads:read", "leads:write", "loyalty:read", "loyalty:write", "events:read", "event-credits:read", "event-credits:write", "tickets:read", "tickets:write", "offline:read", "offline:write", "webhooks:write", "communication:read", "communication:write", "usage:read", "branding:read", "branding:write" ] }, "IntegrationCredentialMetadata": { "type": "object", "additionalProperties": true, "properties": { "contractVersion": { "type": "string", "const": "vsm-api-credential-metadata-v1" }, "delivery": { "type": "string", "const": "show-secret-once" }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 6000 }, "rotationCount": { "type": "integer", "minimum": 0 }, "issuedAt": { "type": "string", "format": "date-time" }, "rotatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "description": "PII-minimal lifecycle metadata; bearer secrets, hashes, request bodies and query values are forbidden" }, "PublicIntegrationCredential": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "kind", "name", "scopes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "kind": { "type": "string", "enum": [ "apiKey", "embed", "webhook", "stripeConnect" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "publicKey": { "type": "string", "pattern": "^vsm_pk_[a-f0-9]{32}$", "description": "Public lookup key; not bearer authentication material" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "public:read", "venues:read", "venues:write", "bookings:read", "bookings:write", "customers:read", "customers:write", "leads:read", "leads:write", "loyalty:read", "loyalty:write", "events:read", "event-credits:read", "event-credits:write", "tickets:read", "tickets:write", "offline:read", "offline:write", "webhooks:write", "communication:read", "communication:write", "usage:read", "branding:read", "branding:write" ] }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "metadata": { "$ref": "#/components/schemas/IntegrationCredentialMetadata" }, "lastUsedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "IntegrationCredentialCreateInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "apiKey", "embed", "webhook" ], "default": "apiKey" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "public:read", "venues:read", "venues:write", "bookings:read", "bookings:write", "customers:read", "customers:write", "leads:read", "leads:write", "loyalty:read", "loyalty:write", "events:read", "event-credits:read", "event-credits:write", "tickets:read", "tickets:write", "offline:read", "offline:write", "webhooks:write", "communication:read", "communication:write", "usage:read", "branding:read", "branding:write" ] }, "minItems": 1, "maxItems": 24, "uniqueItems": true, "default": [ "public:read" ] }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 6000, "default": 120 } } }, "IntegrationCredentialUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "public:read", "venues:read", "venues:write", "bookings:read", "bookings:write", "customers:read", "customers:write", "leads:read", "leads:write", "loyalty:read", "loyalty:write", "events:read", "event-credits:read", "event-credits:write", "tickets:read", "tickets:write", "offline:read", "offline:write", "webhooks:write", "communication:read", "communication:write", "usage:read", "branding:read", "branding:write" ] }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 6000 } }, "minProperties": 1 }, "IntegrationCredentialRotateInput": { "type": "object", "additionalProperties": false, "properties": { "scopes": { "type": "array", "items": { "type": "string", "enum": [ "public:read", "venues:read", "venues:write", "bookings:read", "bookings:write", "customers:read", "customers:write", "leads:read", "leads:write", "loyalty:read", "loyalty:write", "events:read", "event-credits:read", "event-credits:write", "tickets:read", "tickets:write", "offline:read", "offline:write", "webhooks:write", "communication:read", "communication:write", "usage:read", "branding:read", "branding:write" ] }, "minItems": 1, "maxItems": 24, "uniqueItems": true }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 6000 } } }, "IntegrationCredentialListQuery": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "IntegrationCredentialPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIntegrationCredential" }, "maxItems": 100 }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "IntegrationCredentialResult": { "type": "object", "additionalProperties": false, "required": [ "credential" ], "properties": { "credential": { "$ref": "#/components/schemas/PublicIntegrationCredential" } } }, "IntegrationCredentialOneTimeSecretResult": { "type": "object", "additionalProperties": false, "required": [ "credential", "secret" ], "properties": { "credential": { "$ref": "#/components/schemas/PublicIntegrationCredential" }, "secret": { "type": "string", "pattern": "^vsm_sk_[a-f0-9]{64}$", "writeOnly": true, "description": "Returned exactly once; only its SHA-256 hash is stored" } } }, "IntegrationCredentialRevokeResult": { "type": "object", "additionalProperties": false, "required": [ "credential", "unchanged" ], "properties": { "credential": { "$ref": "#/components/schemas/PublicIntegrationCredential" }, "unchanged": { "type": "boolean" } } }, "IntegrationCredentialAuditEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "category", "severity", "action", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 191 }, "actorEmailHash": { "type": "string", "pattern": "^(?:sha256:)?[a-f0-9]{64}$" }, "actorDisplay": { "type": "string", "minLength": 1, "maxLength": 240 }, "category": { "type": "string", "enum": [ "auth", "billing", "booking", "ticketing", "admin", "security", "ops", "webhook", "assistant", "data" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 191 }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 191 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 191 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 191 }, "ipHash": { "type": "string", "pattern": "^(?:sha256:)?[a-f0-9]{64}$" }, "metadata": { "type": "object", "additionalProperties": true, "description": "PII-minimal request outcome metadata without bearer secret, body or query values" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "IntegrationCredentialUsageResult": { "type": "object", "additionalProperties": false, "required": [ "credential", "rateLimitPerMinute", "items" ], "properties": { "credential": { "$ref": "#/components/schemas/PublicIntegrationCredential" }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 6000 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCredentialAuditEvent" }, "maxItems": 50 } } }, "IntegrationCredentialPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/IntegrationCredentialPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "IntegrationCredentialResultEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/IntegrationCredentialResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "IntegrationCredentialOneTimeSecretEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/IntegrationCredentialOneTimeSecretResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "IntegrationCredentialRevokeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/IntegrationCredentialRevokeResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "IntegrationCredentialUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/IntegrationCredentialUsageResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicWebhookEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "url", "events", "active", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "active": { "type": "boolean" }, "lastTestedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookEndpointListQuery": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "WebhookEndpointPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWebhookEndpoint" }, "maxItems": 100 }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "WebhookCreateInput": { "type": "object", "additionalProperties": false, "required": [ "url", "events", "secret" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "active": { "type": "boolean", "default": true }, "secret": { "type": "string", "minLength": 24, "maxLength": 256, "writeOnly": true } } }, "WebhookSigningDescriptor": { "type": "object", "additionalProperties": false, "required": [ "algorithm", "header" ], "properties": { "algorithm": { "type": "string", "const": "HMAC-SHA256" }, "header": { "type": "string", "const": "x-vsm-signature" } } }, "WebhookCreateResult": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "signing" ], "properties": { "endpoint": { "$ref": "#/components/schemas/PublicWebhookEndpoint" }, "signing": { "$ref": "#/components/schemas/WebhookSigningDescriptor" } } }, "WebhookUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "active": { "type": "boolean" } }, "minProperties": 1 }, "WebhookRotateInput": { "type": "object", "additionalProperties": false, "required": [ "secret" ], "properties": { "secret": { "type": "string", "minLength": 24, "maxLength": 256, "writeOnly": true } } }, "WebhookMutationResult": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "$ref": "#/components/schemas/PublicWebhookEndpoint" } } }, "WebhookTestInput": { "type": "object", "additionalProperties": false, "properties": { "signingSecret": { "type": "string", "minLength": 24, "maxLength": 256, "writeOnly": true } } }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "endpointId", "eventId", "eventType", "payload", "status", "attempts", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventType": { "type": "string", "minLength": 1, "maxLength": 120 }, "payload": { "type": "object", "additionalProperties": true, "description": "Exact stored webhook payload" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "responseStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "responseBody": { "type": "string" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryListQuery": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventType": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] } } }, "WebhookDeliveryPage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "maxItems": 100 }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "WebhookTestResult": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "delivery", "queued" ], "properties": { "endpoint": { "$ref": "#/components/schemas/PublicWebhookEndpoint" }, "delivery": { "$ref": "#/components/schemas/WebhookDelivery" }, "queued": { "type": "boolean", "const": true } } }, "WebhookDeliveryRetryResult": { "type": "object", "additionalProperties": false, "required": [ "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "WebhookEndpointPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookEndpointEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicWebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookMutationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookMutationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookTestEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookTestResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookDeliveryPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliveryPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookDeliveryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebhookDeliveryRetryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliveryRetryResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailTemplateKind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "bookingRecovery", "waitlistOffer", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice", "platformNotice", "conversationMessage", "followUpService", "followUpReactivation" ] }, "EmailAudienceKind": { "type": "string", "enum": [ "direct", "bookingGuests", "ticketBuyers", "eventAttendees", "tenantMembers" ] }, "EmailMessageStatus": { "type": "string", "enum": [ "draft", "queued", "processing", "sent", "failed", "cancelled" ] }, "EmailTemplate": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "key", "kind", "locale", "subject", "bodyHtml", "active", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "key": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:[-_.][a-z0-9]+)*$" }, "kind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "bookingRecovery", "waitlistOffer", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice", "platformNotice", "conversationMessage", "followUpService", "followUpReactivation" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "preheader": { "type": "string", "minLength": 0, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "variables": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" } } }, "EmailTemplateCreateInput": { "type": "object", "additionalProperties": false, "required": [ "key", "kind", "subject", "bodyHtml" ], "properties": { "key": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:[-_.][a-z0-9]+)*$" }, "kind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice" ] }, "locale": { "type": "string", "enum": [ "de", "en" ], "default": "de" }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "preheader": { "type": "string", "minLength": 0, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "variables": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean", "default": true } } }, "EmailTemplateUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "preheader": { "type": "string", "minLength": 0, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "variables": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" } } }, "EmailTemplatePage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" }, "maxItems": 100 }, "page": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } } } } }, "EmailTemplateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailTemplatePageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplatePage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailTemplateDeleteResult": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } }, "EmailTemplateDeleteEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplateDeleteResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailMessageCreateInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "recipientEmail", "subject" ], "properties": { "templateId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "bookingConfirmation", "bookingCancellation", "bookingReminder", "eventAnnouncement", "eventChanged", "eventCancelled", "ticketConfirmation", "ticketTransfer", "ticketPromotion", "ticketQueue", "ticketWaitlist", "teamInvite", "magicLink", "securityAlert", "billingNotice" ] }, "audience": { "$ref": "#/components/schemas/EmailAudienceKind", "default": "direct" }, "recipientEmail": { "type": "string", "format": "email", "maxLength": 320 }, "recipientName": { "type": "string", "minLength": 1, "maxLength": 160 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "relatedBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedEventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedTicketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scheduledAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "EmailMessagePage": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" }, "maxItems": 100 }, "page": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } } } } }, "EmailMessageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailMessage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailMessagePageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailMessagePage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailRecipientInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "EmailBroadcastInput": { "type": "object", "additionalProperties": false, "required": [ "kind", "audience", "subject" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "templateId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "const": "eventAnnouncement" }, "audience": { "$ref": "#/components/schemas/EmailAudienceKind" }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/EmailRecipientInput" }, "maxItems": 5000 }, "relatedBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedEventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "relatedTicketOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scheduledAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "EmailBroadcastPreviewRecipient": { "type": "object", "additionalProperties": false, "required": [ "emailMasked" ], "properties": { "emailMasked": { "type": "string", "minLength": 3, "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "EmailBroadcastResult": { "type": "object", "additionalProperties": false, "required": [ "queued", "messages", "preview", "webhooks", "broadcastPlanId", "replayed" ], "properties": { "queued": { "type": "integer", "minimum": 0, "maximum": 5000 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" }, "maxItems": 5000 }, "preview": { "$ref": "#/components/schemas/EmailBroadcastPreview" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "broadcastPlanId": { "type": "string", "minLength": 1, "maxLength": 160 }, "replayed": { "type": "boolean" } } }, "EmailBroadcastPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailBroadcastPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EmailBroadcastResultEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailBroadcastResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingReminderInput": { "type": "object", "additionalProperties": false, "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scheduledAt": { "type": "string", "format": "date-time" }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 } } }, "BookingReminderResult": { "type": "object", "additionalProperties": false, "required": [ "reminder", "cancelledPrevious", "webhooks", "broadcastPlanId", "replayed" ], "properties": { "reminder": { "$ref": "#/components/schemas/EmailMessage" }, "cancelledPrevious": { "type": "integer", "minimum": 0 }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "broadcastPlanId": { "type": "string", "minLength": 1, "maxLength": 160 }, "replayed": { "type": "boolean" } } }, "BookingReminderEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingReminderResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerProfileSearchInput": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } }, "CustomerProfileTimelineItem": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "title", "detail", "timestamp", "href", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 340 }, "kind": { "type": "string", "enum": [ "booking", "ticketOrder", "email", "supportCase", "cancellation", "noShow" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "detail": { "type": "string", "minLength": 0, "maxLength": 5000 }, "timestamp": { "type": "string", "format": "date-time" }, "href": { "type": "string", "minLength": 1, "maxLength": 2048 }, "status": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "CustomerProfile": { "type": "object", "additionalProperties": false, "required": [ "customerKey", "emailMasked", "bookingCount", "ticketOrderCount", "openSupportCaseCount", "bookings", "ticketOrders", "emailMessages", "supportCases", "timeline" ], "properties": { "customerKey": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "emailMasked": { "type": "string", "minLength": 3, "maxLength": 320 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingCount": { "type": "integer", "minimum": 0 }, "ticketOrderCount": { "type": "integer", "minimum": 0 }, "openSupportCaseCount": { "type": "integer", "minimum": 0 }, "lastActivityAt": { "type": "string", "format": "date-time" }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "ticketOrders": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrder" } }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "supportCases": { "type": "array", "items": { "$ref": "#/components/schemas/SupportCase" } }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerProfileTimelineItem" } } } }, "CustomerProfileResult": { "type": "object", "additionalProperties": false, "required": [ "profile" ], "properties": { "profile": { "$ref": "#/components/schemas/CustomerProfile" } } }, "CustomerProfileEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerProfileResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SupportCase": { "type": "object", "additionalProperties": false, "required": [ "id", "caseNumber", "subject", "status", "priority", "category", "lastActivityAt", "responseDueAt", "revision", "slaState", "summary", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "caseNumber": { "type": "string", "minLength": 10, "maxLength": 32 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "category": { "type": "string", "enum": [ "technical", "billing", "account", "bookings", "events", "tickets", "general" ] }, "requesterHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "assignedToUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "lastActivityAt": { "type": "string", "format": "date-time" }, "responseDueAt": { "type": "string", "format": "date-time" }, "firstResponseAt": { "type": "string", "format": "date-time" }, "lastCustomerMessageAt": { "type": "string", "format": "date-time" }, "lastOperatorResponseAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1 }, "slaState": { "type": "string", "enum": [ "onTrack", "dueSoon", "overdue", "waitingOnCustomer", "resolved" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 10000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "SupportCaseAssignInput": { "type": "object", "additionalProperties": false, "properties": { "assignedToUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedRevision": { "type": "integer", "minimum": 1 } } }, "SupportCaseCommentInput": { "type": "object", "additionalProperties": false, "required": [ "comment" ], "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 4000 } } }, "SupportCaseResult": { "type": "object", "additionalProperties": false, "required": [ "supportCase" ], "properties": { "supportCase": { "$ref": "#/components/schemas/SupportCase" } } }, "SupportCaseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SupportCaseResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WaitlistStatus": { "type": "string", "enum": [ "waiting", "offered", "promoted", "cancelled", "expired", "removed" ] }, "WaitlistEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "calendarId", "slotId", "guestName", "guestEmail", "partySize", "status", "position", "requesterHash", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 1, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "note": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "waiting", "offered", "promoted", "cancelled", "expired", "removed" ] }, "position": { "type": "integer", "minimum": 1 }, "requesterHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "offeredAt": { "type": "string", "format": "date-time" }, "offerExpiresAt": { "type": "string", "format": "date-time" }, "notificationMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotedBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotedAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "type": "string", "format": "date-time" } } }, "OperatorWaitlistEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "calendarId", "slotId", "guestName", "guestEmail", "partySize", "status", "position", "requesterHash", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 1, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "note": { "type": "string", "minLength": 0, "maxLength": 5000 }, "status": { "type": "string", "enum": [ "waiting", "offered", "promoted", "cancelled", "expired", "removed" ] }, "position": { "type": "integer", "minimum": 1 }, "requesterHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "offeredAt": { "type": "string", "format": "date-time" }, "offerExpiresAt": { "type": "string", "format": "date-time" }, "notificationMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotedBookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "promotedAt": { "type": "string", "format": "date-time" }, "cancelledAt": { "type": "string", "format": "date-time" }, "offerNotification": { "type": "object", "additionalProperties": false, "required": [ "status", "recoveryAvailable", "renewalAvailable" ], "properties": { "status": { "type": "string", "enum": [ "draft", "queued", "processing", "sent", "failed", "cancelled" ] }, "recoveryAvailable": { "type": "boolean" }, "renewalAvailable": { "type": "boolean" } } }, "slot": { "type": "object", "additionalProperties": false, "required": [ "startsAt", "endsAt", "capacity", "reserved" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "capacity": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "reserved": { "type": "integer", "minimum": 0, "maximum": 1000000 } } } } }, "WaitlistListQuery": { "type": "object", "additionalProperties": false, "properties": { "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "$ref": "#/components/schemas/WaitlistStatus" } } }, "WaitlistListResult": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorWaitlistEntry" } } } }, "WaitlistListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WaitlistListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WaitlistOfferInput": { "type": "object", "additionalProperties": false, "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 0, "maxLength": 200000 }, "bodyText": { "type": "string", "minLength": 0, "maxLength": 200000 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "recoverStoppedMessageId": { "type": "string", "minLength": 1, "maxLength": 191 } } }, "WaitlistOfferResult": { "type": "object", "additionalProperties": false, "required": [ "entry", "message", "replayed", "webhooks" ], "properties": { "entry": { "$ref": "#/components/schemas/WaitlistEntry" }, "message": { "$ref": "#/components/schemas/EmailMessage" }, "replayed": { "type": "boolean" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "WaitlistOfferEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WaitlistOfferResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WaitlistPromotionResult": { "type": "object", "additionalProperties": false, "required": [ "entry", "booking", "message", "replayed", "webhooks" ], "properties": { "entry": { "$ref": "#/components/schemas/WaitlistEntry" }, "booking": { "$ref": "#/components/schemas/Booking" }, "message": { "oneOf": [ { "$ref": "#/components/schemas/EmailMessage" }, { "type": "null" } ] }, "replayed": { "type": "boolean" }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" } } }, "WaitlistPromotionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WaitlistPromotionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OperatorConversationListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "assignee": { "type": "string", "minLength": 1, "maxLength": 160 }, "q": { "type": "string", "minLength": 2, "maxLength": 100 } } }, "CustomerConversationListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] } } }, "OperatorConversationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "subject", "bodyText" ], "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "prospectContactId": { "type": "string", "minLength": 1, "maxLength": 160 }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 10000 }, "context": { "$ref": "#/components/schemas/ConversationContextInput" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAttachmentInput" }, "maxItems": 3 } } }, "CustomerConversationReplyInput": { "type": "object", "additionalProperties": false, "required": [ "bodyText" ], "properties": { "bodyText": { "type": "string", "minLength": 1, "maxLength": 10000 }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationAttachmentInput" }, "maxItems": 3 } } }, "ConversationThreadResult": { "type": "object", "additionalProperties": false, "required": [ "thread" ], "properties": { "thread": { "$ref": "#/components/schemas/ConversationThread" } } }, "ConversationListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ConversationList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationTextAttachment": { "type": "string", "format": "binary", "description": "Immutable UTF-8 text attachment body" }, "EmailProviderEventInput": { "oneOf": [ { "$ref": "#/components/schemas/LegacyEmailProviderEventInput" }, { "$ref": "#/components/schemas/SignedTransportAcceptedInput" }, { "$ref": "#/components/schemas/SignedTransportNotAcceptedInput" } ] }, "EmailProviderEventResult": { "type": "object", "additionalProperties": false, "required": [ "received", "provider", "eventId" ], "properties": { "received": { "type": "boolean", "const": true }, "duplicate": { "type": "boolean" }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "provider": { "type": "string", "minLength": 2, "maxLength": 40, "pattern": "^[a-z0-9_-]+$" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "DELIVERED", "BOUNCED", "COMPLAINED", "DROPPED", "OPENED", "CLICKED", "UNKNOWN" ] }, "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "action": { "type": "string", "enum": [ "message_marked_sent", "message_failed_and_suppressed", "event_recorded" ] } } }, "EmailProviderEventEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmailProviderEventResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationMailListQuery": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "PrivacyConsentLocalizedCopy": { "type": "object", "additionalProperties": false, "required": [ "title", "description", "impact" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "impact": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "PrivacyConsentCategoryCopy": { "type": "object", "additionalProperties": false, "required": [ "de", "en" ], "properties": { "de": { "$ref": "#/components/schemas/PrivacyConsentLocalizedCopy" }, "en": { "$ref": "#/components/schemas/PrivacyConsentLocalizedCopy" } } }, "PrivacyConsentCategory": { "type": "object", "additionalProperties": false, "required": [ "key", "required", "displayOrder", "copy" ], "properties": { "key": { "type": "string", "enum": [ "required", "analytics", "marketing" ] }, "required": { "type": "boolean" }, "displayOrder": { "type": "integer", "minimum": 0, "maximum": 999 }, "copy": { "$ref": "#/components/schemas/PrivacyConsentCategoryCopy" } } }, "PrivacyConsentService": { "type": "object", "additionalProperties": false, "required": [ "key", "category", "name", "provider", "purpose", "lawfulBasis", "dataCategories", "usesDeviceStorage", "transferCountries", "transferMechanism", "retention", "docsUrl", "required", "displayOrder", "status" ], "properties": { "key": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" }, "category": { "type": "string", "enum": [ "required", "analytics", "marketing" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "provider": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "purpose": { "type": "object", "additionalProperties": false, "required": [ "de", "en" ], "properties": { "de": { "type": "string", "minLength": 1, "maxLength": 2000 }, "en": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "lawfulBasis": { "type": "string", "minLength": 1, "maxLength": 500 }, "dataCategories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 50 }, "usesDeviceStorage": { "type": "boolean" }, "transferCountries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 50 }, "transferMechanism": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "retention": { "type": "object", "additionalProperties": false, "required": [ "de", "en" ], "properties": { "de": { "type": "string", "minLength": 1, "maxLength": 2000 }, "en": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "docsUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "required": { "type": "boolean" }, "displayOrder": { "type": "integer", "minimum": 0, "maximum": 999 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] } } }, "PrivacyConsentPolicyDocument": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "categories", "services" ], "properties": { "schemaVersion": { "const": "vsm-privacy-consent-policy-v1" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyConsentCategory" }, "maxItems": 3, "minItems": 3 }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyConsentService" }, "maxItems": 100 } } }, "PrivacyConsentPolicyDiffCount": { "type": "object", "additionalProperties": false, "required": [ "added", "changed", "removed" ], "properties": { "added": { "type": "integer", "minimum": 0 }, "changed": { "type": "integer", "minimum": 0 }, "removed": { "type": "integer", "minimum": 0 } } }, "PrivacyConsentPolicyDiff": { "type": "object", "additionalProperties": false, "required": [ "categories", "services", "totalChanges" ], "properties": { "categories": { "$ref": "#/components/schemas/PrivacyConsentPolicyDiffCount" }, "services": { "$ref": "#/components/schemas/PrivacyConsentPolicyDiffCount" }, "totalChanges": { "type": "integer", "minimum": 0 } } }, "PrivacyConsentPolicyVersion": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "revision", "status", "document", "changeSummary", "basedOnVersion", "rollbackOfVersion", "createdByUserId", "updatedByUserId", "publishedByUserId", "publishedAt", "supersededAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "version": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "published", "superseded" ] }, "document": { "$ref": "#/components/schemas/PrivacyConsentPolicyDocument" }, "changeSummary": { "oneOf": [ { "$ref": "#/components/schemas/PrivacyConsentPolicyDiff" }, { "type": "null" } ] }, "basedOnVersion": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "rollbackOfVersion": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "createdByUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "updatedByUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "publishedByUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "publishedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersededAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PrivacyConsentAdminState": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "published", "draft", "history" ], "properties": { "schemaVersion": { "const": "vsm-privacy-consent-policy-v1" }, "published": { "$ref": "#/components/schemas/PrivacyConsentPolicyVersion" }, "draft": { "oneOf": [ { "$ref": "#/components/schemas/PrivacyConsentPolicyVersion" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyConsentPolicyVersion" }, "maxItems": 1000 } } }, "PublicPrivacyConsentPolicy": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "version", "publishedAt", "document" ], "properties": { "schemaVersion": { "const": "vsm-privacy-consent-policy-v1" }, "version": { "type": "integer", "minimum": 1 }, "publishedAt": { "type": "string", "format": "date-time" }, "document": { "$ref": "#/components/schemas/PrivacyConsentPolicyDocument" } } }, "PrivacyConsentDecision": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "categories", "services" ], "properties": { "schemaVersion": { "const": "vsm-privacy-consent-decision-v1" }, "categories": { "type": "object", "additionalProperties": false, "required": [ "required", "analytics", "marketing" ], "properties": { "required": { "type": "boolean", "const": true }, "analytics": { "type": "boolean" }, "marketing": { "type": "boolean" } } }, "services": { "type": "object", "additionalProperties": { "type": "boolean" }, "maxProperties": 100 } } }, "PrivacyConsentDecisionView": { "type": "object", "additionalProperties": false, "required": [ "id", "policyVersion", "source", "locale", "decision", "recordedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "policyVersion": { "type": "integer", "minimum": 1 }, "source": { "type": "string", "enum": [ "banner", "preferenceCenter", "customerAccount", "api" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "decision": { "$ref": "#/components/schemas/PrivacyConsentDecision" }, "recordedAt": { "type": "string", "format": "date-time" } } }, "PrivacyConsentDraftInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "document" ], "properties": { "expectedRevision": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "document": { "$ref": "#/components/schemas/PrivacyConsentPolicyDocument" } } }, "PrivacyConsentPublishInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 } } }, "PrivacyConsentRollbackInput": { "type": "object", "additionalProperties": false, "required": [ "targetVersion" ], "properties": { "targetVersion": { "type": "integer", "minimum": 1 } } }, "PublicPrivacyConsentDecisionInput": { "type": "object", "additionalProperties": false, "required": [ "locale", "source", "decision" ], "properties": { "locale": { "type": "string", "enum": [ "de", "en" ] }, "source": { "type": "string", "enum": [ "banner", "preferenceCenter" ] }, "decision": { "type": "object", "additionalProperties": false, "required": [ "categories" ], "properties": { "categories": { "type": "object", "additionalProperties": false, "properties": { "required": { "type": "boolean", "const": true }, "analytics": { "type": "boolean" }, "marketing": { "type": "boolean" } } }, "services": { "type": "object", "additionalProperties": { "type": "boolean" }, "maxProperties": 100 } } } } }, "PrivacyConsentPolicyAuditItem": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "actorUserId", "resourceId", "metadata", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "action": { "type": "string", "minLength": 1, "maxLength": 160 }, "actorUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "resourceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "PrivacyConsentPolicyAuditResult": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyConsentPolicyAuditItem" }, "maxItems": 100 } } }, "PublicPrivacyConsentDecisionState": { "type": "object", "additionalProperties": false, "required": [ "policyVersion", "decision" ], "properties": { "policyVersion": { "type": "integer", "minimum": 1 }, "decision": { "oneOf": [ { "$ref": "#/components/schemas/PrivacyConsentDecisionView" }, { "type": "null" } ] } } }, "PublicPrivacyConsentDecisionResult": { "type": "object", "additionalProperties": false, "required": [ "decision" ], "properties": { "decision": { "$ref": "#/components/schemas/PrivacyConsentDecisionView" } } }, "PrivacyConsentAdminStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PrivacyConsentAdminState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PrivacyConsentPolicyAuditEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PrivacyConsentPolicyAuditResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicPrivacyConsentPolicyEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicPrivacyConsentPolicy" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicPrivacyConsentDecisionStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicPrivacyConsentDecisionState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicPrivacyConsentDecisionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicPrivacyConsentDecisionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantPrivacyRequestInput": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 5000 }, "contactEmail": { "type": "string", "format": "email", "maxLength": 320 }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional operator-supplied legal or support context; contact e-mail is stored only as a digest" } } }, "TenantPrivacyRequestStatus": { "type": "object", "additionalProperties": false, "required": [ "type", "status", "supportCaseId" ], "properties": { "type": { "type": "string", "enum": [ "export", "deletion" ] }, "status": { "type": "string", "const": "accepted" }, "supportCaseId": { "type": "string", "minLength": 1, "maxLength": 191 } } }, "TenantPrivacyExportActor": { "type": "object", "additionalProperties": false, "required": [ "userId", "email" ], "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 191 }, "email": { "type": "string", "format": "email", "maxLength": 320 } } }, "TenantPrivacyExportEmbedSession": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "origin", "mode", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "origin": { "type": "string", "format": "uri", "maxLength": 2048 }, "mode": { "type": "string", "enum": [ "calendar", "events", "tickets" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TenantPrivacyExportAssistantRun": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "task", "locale", "model", "provider", "status", "usedFallback", "tokensInput", "tokensOutput", "tokensTotal", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "userId": { "type": "string", "minLength": 1, "maxLength": 191 }, "task": { "type": "string", "enum": [ "eventDescription", "bookingRules", "ticketStructure", "faqTooltips" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "provider": { "type": "string", "enum": [ "openai", "fallback" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "blocked", "rateLimited" ] }, "usedFallback": { "type": "boolean" }, "tokensInput": { "type": "integer", "minimum": 0 }, "tokensOutput": { "type": "integer", "minimum": 0 }, "tokensTotal": { "type": "integer", "minimum": 0 }, "promptHash": { "type": "string", "minLength": 1, "maxLength": 128 }, "inputSummary": { "type": "string", "minLength": 0, "maxLength": 500 }, "outputPreview": { "type": "string" }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 120 }, "errorMessage": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Assistant run metadata" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TenantPrivacyExportFeatureOverride": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "feature", "status", "reason", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "expired" ] }, "reason": { "type": "string", "maxLength": 10000 }, "createdByUserId": { "type": "string", "minLength": 1, "maxLength": 191 }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Feature override audit metadata" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TenantPrivacyExportAuditEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "category", "severity", "action", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 191 }, "actorEmailHash": { "type": "string", "pattern": "^(?:sha256:)?[a-f0-9]{64}$" }, "actorDisplay": { "type": "string", "minLength": 1, "maxLength": 160 }, "category": { "type": "string", "enum": [ "auth", "billing", "booking", "ticketing", "admin", "security", "ops", "webhook", "assistant", "data" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 220 }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 120 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 191 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ipHash": { "type": "string", "pattern": "^(?:sha256:)?[a-f0-9]{64}$" }, "metadata": { "type": "object", "additionalProperties": true, "description": "PII-minimal immutable audit metadata" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TenantPrivacyExportResources": { "type": "object", "additionalProperties": false, "required": [ "tenant", "communicationPolicy", "communicationUsage", "communicationUsageReservations", "communicationUsageEntries", "communicationUsageEvidence", "communicationUsageResolutions", "communicationUsageWarnings", "familyTransportEvidence", "familyTransportResolutions", "emailBroadcastPlans", "waitlistOfferCommands", "tenantMembers", "familyParticipants", "familyWorkflowEvents", "participantRepresentations", "participantCommands", "bookingParticipants", "locations", "calendars", "bookings", "bookingServices", "bookingReminderPlans", "bookingRecoveryPlans", "bookingRecoveryRetryCommands", "seatMaps", "seatHolds", "seatAssignments", "events", "ticketOfferings", "ticketOrders", "tickets", "emailTemplates", "emailMessages", "embedSessions", "webhooks", "webhookDeliveries", "integrationCredentials", "assistantRuns", "featureOverrides", "supportCases", "auditEvents" ], "properties": { "tenant": { "$ref": "#/components/schemas/AuthTenant" }, "communicationUsage": { "anyOf": [ { "$ref": "#/components/schemas/CommunicationUsage" }, { "type": "null" } ] }, "communicationUsageReservations": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationUsageReservationExport" } }, "communicationUsageEntries": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationUsageEntryExport" } }, "communicationUsageEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationUsageEvidenceExport" } }, "communicationUsageResolutions": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationUsageResolutionExport" } }, "communicationUsageWarnings": { "type": "array", "items": { "$ref": "#/components/schemas/CommunicationUsageWarningExport" } }, "familyTransportEvidence": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyTransportEvidenceExport" } }, "familyTransportResolutions": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyTransportResolutionExport" } }, "communicationPolicy": { "anyOf": [ { "$ref": "#/components/schemas/CommunicationPolicy" }, { "type": "null" } ] }, "emailBroadcastPlans": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBroadcastPlanView" } }, "waitlistOfferCommands": { "type": "array", "items": { "$ref": "#/components/schemas/WaitlistOfferCommandExport" } }, "prospectContacts": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionContactRecord" } }, "leadOpportunities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored flat opportunities including current Booking/Membership/assignment links; history/tasks are separate paginated resources." } }, "leadHistory": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionHistoryRecord" } }, "leadCommands": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Redacted acquisition replay receipts; no request digests." } }, "leadBookingCaptures": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionBookingCaptureRecord" } }, "leadBookingPolicies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Tenant booking intake policies." } }, "leadPhaseConfigurations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Phase version snapshots through the shared export cutoff." } }, "leadPhaseDefinitions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Phase definitions through the same version cutoff." } }, "leadTasks": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTaskRecord" } }, "leadTaskHistory": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTaskHistoryRecord" } }, "leadTaskCircles": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Stored location circle policies and rotation cursor." } }, "leadTaskCircleMembers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Explicit circle membership and persistent suspension." } }, "leadTaskCommands": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Redacted callback replay receipts; no request digests." } }, "textSenders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "F05/F06 registered sender numbers and their status." } }, "textMessages": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "F05/F06 SMS/WhatsApp messages; request digests and claim state stay internal." } }, "textSuppressions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "F05/F06 opt-out suppressions per channel and number." } }, "textOptIns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "F06 purpose-bound opt-ins (purpose, source, evidence, capture and revocation)." } }, "bookingWhatsAppPlans": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Booking-form WhatsApp consent proofs (number, text version, locale, timestamp) and notification state." } }, "serviceRequests": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "F21 service requests; command keys stay internal." } }, "tenantMembers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthTenantMember" } }, "familyParticipants": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyParticipantPrivacyExport" } }, "familyWorkflowEvents": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyWorkflowEvent" } }, "participantRepresentations": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipantRepresentationPrivacyExport" } }, "participantCommands": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipantCommandPrivacyExport" } }, "bookingParticipants": { "type": "array", "items": { "$ref": "#/components/schemas/BookingParticipantPrivacyExport" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "calendars": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "bookingServices": { "type": "array", "items": { "$ref": "#/components/schemas/BookingService" } }, "bookingReminderPlans": { "type": "array", "items": { "$ref": "#/components/schemas/BookingReminderPlanView" } }, "bookingRecoveryPlans": { "type": "array", "items": { "$ref": "#/components/schemas/BookingRecoveryPlanView" } }, "bookingRecoveryRetryCommands": { "type": "array", "items": { "$ref": "#/components/schemas/BookingRecoveryRetryCommandExport" } }, "seatMaps": { "type": "array", "items": { "$ref": "#/components/schemas/SeatMap" } }, "seatHolds": { "type": "array", "items": { "$ref": "#/components/schemas/SeatHold" } }, "seatAssignments": { "type": "array", "items": { "$ref": "#/components/schemas/SeatAssignment" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "ticketOfferings": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOffering" } }, "ticketOrders": { "type": "array", "items": { "$ref": "#/components/schemas/TicketOrder" } }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "emailTemplates": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "embedSessions": { "type": "array", "items": { "$ref": "#/components/schemas/TenantPrivacyExportEmbedSession" } }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWebhookEndpoint" } }, "webhookDeliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "integrationCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIntegrationCredential" } }, "assistantRuns": { "type": "array", "items": { "$ref": "#/components/schemas/TenantPrivacyExportAssistantRun" } }, "featureOverrides": { "type": "array", "items": { "$ref": "#/components/schemas/TenantPrivacyExportFeatureOverride" } }, "supportCases": { "type": "array", "items": { "$ref": "#/components/schemas/SupportCase" } }, "auditEvents": { "type": "array", "items": { "$ref": "#/components/schemas/TenantPrivacyExportAuditEvent" } } } }, "TenantPrivacyExportResult": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "tenantId", "generatedBy", "resources", "auditEventId" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "generatedBy": { "$ref": "#/components/schemas/TenantPrivacyExportActor" }, "resources": { "$ref": "#/components/schemas/TenantPrivacyExportResources" }, "auditEventId": { "type": "string", "minLength": 1, "maxLength": 191 } } }, "TenantPrivacyRequestResult": { "type": "object", "additionalProperties": false, "required": [ "request", "supportCase", "auditEvent" ], "properties": { "request": { "$ref": "#/components/schemas/TenantPrivacyRequestStatus" }, "supportCase": { "$ref": "#/components/schemas/SupportCase" }, "auditEvent": { "$ref": "#/components/schemas/TenantPrivacyExportAuditEvent" } } }, "TenantPrivacyExportEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantPrivacyExportResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantPrivacyRequestEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/TenantPrivacyRequestResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsAlertAudience": { "type": "object", "additionalProperties": false, "required": [ "version", "sources", "purpose", "activitySinceDays", "minOrders", "segments" ], "properties": { "version": { "type": "string", "const": "vsm-event-alert-audience-v1" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "ticketBuyers", "bookingGuests", "waitlist", "customerSegments" ] }, "minItems": 1, "maxItems": 4, "uniqueItems": true }, "purpose": { "type": "string", "enum": [ "transactional", "marketing" ] }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 191 }, "activitySinceDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "minOrders": { "type": "integer", "minimum": 0, "maximum": 100 }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 0, "maxItems": 20, "uniqueItems": true } } }, "EventOperationsAlertAudiencePreviewInput": { "type": "object", "additionalProperties": false, "required": [ "audience", "channels" ], "properties": { "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true } } }, "EventOperationsAlertChannelEligibility": { "type": "object", "additionalProperties": false, "required": [ "eligible", "reason" ], "properties": { "eligible": { "type": "boolean" }, "reason": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] } } }, "EventOperationsAlertAudienceMember": { "type": "object", "additionalProperties": false, "required": [ "customerId", "emailMasked", "name", "sources", "orderCount", "lastActivityAt", "channels" ], "properties": { "customerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "emailMasked": { "type": "string", "minLength": 1, "maxLength": 320 }, "name": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 4, "uniqueItems": true }, "orderCount": { "type": "integer", "minimum": 0 }, "lastActivityAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "channels": { "type": "object", "additionalProperties": false, "required": [ "email", "inApp", "push" ], "properties": { "email": { "$ref": "#/components/schemas/EventOperationsAlertChannelEligibility" }, "inApp": { "$ref": "#/components/schemas/EventOperationsAlertChannelEligibility" }, "push": { "$ref": "#/components/schemas/EventOperationsAlertChannelEligibility" } } } } }, "EventOperationsAlertAudiencePreview": { "type": "object", "additionalProperties": false, "required": [ "audience", "totals", "members" ], "properties": { "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" }, "totals": { "type": "object", "additionalProperties": false, "required": [ "resolved", "eligible", "excluded", "truncated", "bySource", "byChannel" ], "properties": { "resolved": { "type": "integer", "minimum": 0 }, "eligible": { "type": "integer", "minimum": 0 }, "excluded": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "bySource": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "byChannel": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsAlertAudienceMember" }, "maxItems": 5000 } } }, "EventOperationsAlertAudiencePreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsAlertAudiencePreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsAlertCampaignInput": { "type": "object", "additionalProperties": false, "required": [ "template", "audience", "channels", "subject", "bodyText" ], "properties": { "template": { "type": "string", "enum": [ "publish", "update", "cancelled", "reminder", "lowInventory", "custom" ] }, "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 100000 }, "ctaLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "ctaUrl": { "type": "string", "minLength": 1, "maxLength": 2000 }, "scheduledAt": { "type": "string", "format": "date-time" } } }, "EventOperationsAlertCampaign": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "eventInstanceId", "template", "purpose", "status", "audience", "channels", "subject", "bodyText", "bodyHtml", "ctaLabel", "ctaUrl", "scheduledAt", "queuedAt", "completedAt", "dedupeKey", "resolvedRecipients", "excludedRecipients", "deliveryCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventInstanceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "template": { "type": "string", "enum": [ "publish", "update", "cancelled", "reminder", "lowInventory", "custom" ] }, "purpose": { "type": "string", "enum": [ "transactional", "marketing" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "partial_failed", "cancelled" ] }, "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyHtml": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100000 }, { "type": "null" } ] }, "ctaLabel": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "ctaUrl": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "scheduledAt": { "type": "string", "format": "date-time" }, "queuedAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dedupeKey": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "resolvedRecipients": { "type": "integer", "minimum": 0 }, "excludedRecipients": { "type": "integer", "minimum": 0 }, "deliveryCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsAlertCampaignCreateResult": { "type": "object", "additionalProperties": false, "required": [ "campaign", "replayed" ], "properties": { "campaign": { "$ref": "#/components/schemas/EventOperationsAlertCampaign" }, "replayed": { "type": "boolean" } } }, "EventOperationsAlertCampaignCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsAlertCampaignCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsAlertCampaignResult": { "type": "object", "additionalProperties": false, "required": [ "campaign" ], "properties": { "campaign": { "$ref": "#/components/schemas/EventOperationsAlertCampaign" } } }, "EventOperationsAlertCampaignEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsAlertCampaignResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsAlertAutomationInput": { "type": "object", "additionalProperties": false, "required": [ "enabled", "thresholdPercent", "cooldownHours", "maxRuns", "channels", "audience" ], "properties": { "enabled": { "type": "boolean" }, "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 50 }, "cooldownHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "maxRuns": { "type": "integer", "minimum": 1, "maximum": 20 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" } } }, "EventOperationsAlertAutomation": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "offeringId", "enabled", "thresholdPercent", "cooldownHours", "maxRuns", "runCount", "channels", "audience", "lastTriggeredAt", "lastRemainingQuantity", "nextEligibleAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 191 }, "enabled": { "type": "boolean" }, "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 50 }, "cooldownHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "maxRuns": { "type": "integer", "minimum": 1, "maximum": 20 }, "runCount": { "type": "integer", "minimum": 0 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "audience": { "$ref": "#/components/schemas/EventOperationsAlertAudience" }, "lastTriggeredAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastRemainingQuantity": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "nextEligibleAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsAlertAutomationResult": { "type": "object", "additionalProperties": false, "required": [ "automation" ], "properties": { "automation": { "$ref": "#/components/schemas/EventOperationsAlertAutomation" } } }, "EventOperationsAlertAutomationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsAlertAutomationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsAlertWorkspace": { "type": "object", "additionalProperties": false, "required": [ "event", "capabilities", "campaigns", "offerings" ], "properties": { "event": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "status", "instances" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "instances": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "startsAt", "endsAt", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "cancelled" ] } } }, "maxItems": 100 } } }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "email", "inApp", "push" ], "properties": { "email": { "type": "boolean", "const": true }, "inApp": { "type": "boolean", "const": true }, "push": { "type": "boolean" } } }, "campaigns": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EventOperationsAlertCampaign" }, { "type": "object", "additionalProperties": false, "required": [ "analytics" ], "properties": { "analytics": { "type": "object", "additionalProperties": false, "required": [ "states", "opened", "clicked" ], "properties": { "states": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "opened": { "type": "integer", "minimum": 0 }, "clicked": { "type": "integer", "minimum": 0 } } } } } ] }, "maxItems": 50 }, "offerings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "status", "totalLimit", "eventInstanceId", "ticketTypes", "automation" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "totalLimit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "eventInstanceId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "ticketTypes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "inventoryLimit", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "inventoryLimit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "maxItems": 100 }, "automation": { "oneOf": [ { "$ref": "#/components/schemas/EventOperationsAlertAutomation" }, { "type": "null" } ] } } }, "maxItems": 100 } } }, "EventOperationsAlertWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsAlertWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsCreditConfigurationInput": { "type": "object", "additionalProperties": false, "required": [ "enabled", "currency", "topUpMinAmount", "topUpMaxAmount", "refundsEnabled" ], "properties": { "enabled": { "type": "boolean" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "topUpMinAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "topUpMaxAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "refundsEnabled": { "type": "boolean" } } }, "EventOperationsCreditConfiguration": { "type": "object", "additionalProperties": false, "required": [ "enabled", "currency", "topUpMinAmount", "topUpMaxAmount", "refundsEnabled" ], "properties": { "enabled": { "type": "boolean" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "topUpMinAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "topUpMaxAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "refundsEnabled": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsCreditConfigurationResult": { "type": "object", "additionalProperties": false, "required": [ "configuration" ], "properties": { "configuration": { "$ref": "#/components/schemas/EventOperationsCreditConfiguration" } } }, "EventOperationsCreditConfigurationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsCreditConfigurationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsCreditChargeConfirmationInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 256 } } }, { "type": "object", "additionalProperties": false, "required": [ "manualCode" ], "properties": { "manualCode": { "type": "string", "minLength": 8, "maxLength": 16 } } } ] }, "EventOperationsCreditTransaction": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "customerId", "kind", "status", "amountMinor", "currency", "reference", "failureCode", "completedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 191 }, "kind": { "type": "string", "enum": [ "top_up", "charge", "charge_refund", "cash_refund", "adjustment", "chargeback", "reversal" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "partially_succeeded", "failed", "cancelled", "reversed" ] }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "reference": { "type": "string", "minLength": 1, "maxLength": 191 }, "failureCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsCreditBalance": { "type": "object", "additionalProperties": false, "required": [ "settledMinor", "availableMinor", "reservedChargeMinor", "pendingTopUpMinor", "pendingRefundMinor", "currency" ], "properties": { "settledMinor": { "type": "integer" }, "availableMinor": { "type": "integer" }, "reservedChargeMinor": { "type": "integer", "minimum": 0 }, "offlineReservedMinor": { "type": "integer", "minimum": 0 }, "pendingTopUpMinor": { "type": "integer", "minimum": 0 }, "pendingRefundMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, "EventOperationsCreditReconciliation": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "status", "currency", "ledgerTopUpMinor", "ledgerCashRefundMinor", "providerTopUpMinor", "providerCashRefundMinor", "driftMinor", "debitsFrozen", "providerObjectCount", "startedAt", "completedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "status": { "type": "string", "enum": [ "matched", "drift", "failed" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ledgerTopUpMinor": { "type": "integer", "minimum": 0 }, "ledgerCashRefundMinor": { "type": "integer", "minimum": 0 }, "providerTopUpMinor": { "type": "integer", "minimum": 0 }, "providerCashRefundMinor": { "type": "integer", "minimum": 0 }, "driftMinor": { "type": "integer" }, "debitsFrozen": { "type": "boolean" }, "providerObjectCount": { "type": "integer", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "EventOperationsCreditOperatorWorkspace": { "type": "object", "additionalProperties": false, "required": [ "version", "event", "accounts", "transactions", "reconciliation" ], "properties": { "version": { "type": "string", "const": "vsm-event-credit-operator-workspace-v1" }, "event": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug", "status", "configuration" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "configuration": { "$ref": "#/components/schemas/EventOperationsCreditConfiguration" } } }, "accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "customer", "balance" ], "properties": { "customer": { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "primaryEmail", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 220 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 }, "status": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "balance": { "$ref": "#/components/schemas/EventOperationsCreditBalance" } } }, "maxItems": 50 }, "transactions": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EventOperationsCreditTransaction" }, { "type": "object", "additionalProperties": false, "required": [ "customer" ], "properties": { "customer": { "type": "object", "additionalProperties": false, "required": [ "displayName", "primaryEmail" ], "properties": { "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 220 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 } } } } } ] }, "maxItems": 100 }, "reconciliation": { "oneOf": [ { "$ref": "#/components/schemas/EventOperationsCreditReconciliation" }, { "type": "null" } ] } } }, "EventOperationsCreditOperatorWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsCreditOperatorWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsCreditTransactionResult": { "type": "object", "additionalProperties": false, "required": [ "transaction", "replayed" ], "properties": { "transaction": { "$ref": "#/components/schemas/EventOperationsCreditTransaction" }, "replayed": { "type": "boolean" } } }, "EventOperationsCreditTransactionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsCreditTransactionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsCreditReconciliationResult": { "type": "object", "additionalProperties": false, "required": [ "reconciliation", "replayed" ], "properties": { "reconciliation": { "$ref": "#/components/schemas/EventOperationsCreditReconciliation" }, "replayed": { "type": "boolean" } } }, "EventOperationsCreditReconciliationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsCreditReconciliationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsArtistExternalLinks": { "type": "object", "additionalProperties": false, "properties": { "website": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "spotify": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "instagram": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "facebook": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "youtube": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "EventOperationsArtistRelease": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "releasedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "type": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "EventOperationsArtistCreateInput": { "type": "object", "additionalProperties": false, "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 20000 }, { "type": "null" } ] }, "genres": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 0, "maxItems": 20, "uniqueItems": true }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "thumbnailUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "externalLinks": { "$ref": "#/components/schemas/EventOperationsArtistExternalLinks" }, "recentReleases": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsArtistRelease" }, "maxItems": 20 }, "musicBrainzId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "spotifyId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] } } }, "EventOperationsArtistUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 20000 }, { "type": "null" } ] }, "genres": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 0, "maxItems": 20, "uniqueItems": true }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "thumbnailUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "externalLinks": { "$ref": "#/components/schemas/EventOperationsArtistExternalLinks" }, "recentReleases": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsArtistRelease" }, "maxItems": 20 }, "musicBrainzId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "spotifyId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] } }, "minProperties": 1 }, "EventOperationsArtist": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "name", "slug", "genres", "externalLinks", "recentReleases", "syncStatus", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 220 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "bio": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 20000 }, { "type": "null" } ] }, "genres": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 0, "maxItems": 20, "uniqueItems": true }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "thumbnailUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, { "type": "null" } ] }, "countryCode": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "externalLinks": { "$ref": "#/components/schemas/EventOperationsArtistExternalLinks" }, "recentReleases": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsArtistRelease" }, "maxItems": 20 }, "musicBrainzId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "spotifyId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "syncStatus": { "type": "string", "enum": [ "pending", "synced", "failed", "manual" ] }, "lastSyncedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "syncError": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 1000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsArtistEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsArtist" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsArtistListResult": { "type": "object", "additionalProperties": false, "required": [ "artists" ], "properties": { "artists": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsArtist" }, "maxItems": 100 } } }, "EventOperationsArtistListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsArtistListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsLineupReplaceInput": { "type": "object", "additionalProperties": false, "required": [ "organizerId", "artists" ], "properties": { "organizerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "artists": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "artistId", "role" ], "properties": { "artistId": { "type": "string", "minLength": 1, "maxLength": 191 }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "oneOf": [ { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "setDurationMinutes": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 1440 }, { "type": "null" } ] }, "stageName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 220 }, { "type": "null" } ] } } }, "minItems": 0, "maxItems": 50, "uniqueItems": true } } }, "EventOperationsLineupEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "eventId", "artistId", "sortOrder", "role", "artist", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "artistId": { "type": "string", "minLength": 1, "maxLength": 191 }, "sortOrder": { "type": "integer", "minimum": 0 }, "role": { "type": "string", "enum": [ "headliner", "support", "performer", "dj", "host", "specialGuest" ] }, "setTime": { "type": "string", "minLength": 5, "maxLength": 5 }, "setDurationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "stageName": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 220 }, "artist": { "$ref": "#/components/schemas/EventOperationsArtist" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsLineup": { "type": "object", "additionalProperties": false, "required": [ "eventId", "organizer", "artists" ], "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "organizer": { "oneOf": [ { "$ref": "#/components/schemas/EventOrganizer" }, { "type": "null" } ] }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsLineupEntry" }, "maxItems": 50 } } }, "EventOperationsLineupEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsLineup" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsMediaRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "eventId", "assetId", "role", "sortOrder", "altText", "focalX", "focalY", "cropAspect", "asset", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "assetId": { "type": "string", "minLength": 1, "maxLength": 191 }, "role": { "type": "string", "enum": [ "hero", "gallery", "social" ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 }, "focalX": { "type": "integer", "minimum": 0, "maximum": 100 }, "focalY": { "type": "integer", "minimum": 0, "maximum": 100 }, "cropAspect": { "type": "string", "enum": [ "original", "wide", "square", "portrait" ] }, "asset": { "type": "object", "additionalProperties": false, "required": [ "originalName", "mimeType", "sizeBytes", "width", "height", "sha256" ], "properties": { "originalName": { "type": "string", "minLength": 1, "maxLength": 500 }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "sizeBytes": { "type": "integer", "minimum": 1 }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "contentUrl": { "type": "string", "minLength": 1, "maxLength": 4096 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsBrandingTemplate": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "name", "description", "theme", "accentColor", "lastUsedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "theme": { "$ref": "#/components/schemas/EventBrandingTheme" }, "accentColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "lastUsedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventOperationsMediaBrandingWorkspace": { "type": "object", "additionalProperties": false, "required": [ "eventId", "media", "branding", "templates" ], "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsMediaRecord" }, "maxItems": 14 }, "branding": { "$ref": "#/components/schemas/EventBrandingTheme" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsBrandingTemplate" }, "maxItems": 100 } } }, "EventOperationsMediaBrandingWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsMediaBrandingWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsMediaUploadInput": { "type": "object", "additionalProperties": false, "required": [ "file", "altText", "role" ], "properties": { "file": { "type": "string", "format": "binary" }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 }, "role": { "type": "string", "enum": [ "hero", "gallery", "social" ] }, "cropAspect": { "type": "string", "enum": [ "original", "wide", "square", "portrait" ] }, "focalX": { "type": "integer", "minimum": 0, "maximum": 100 }, "focalY": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "EventOperationsMediaUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "altText": { "type": "string", "minLength": 1, "maxLength": 500 }, "role": { "type": "string", "enum": [ "hero", "gallery", "social" ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "cropAspect": { "type": "string", "enum": [ "original", "wide", "square", "portrait" ] }, "focalX": { "type": "integer", "minimum": 0, "maximum": 100 }, "focalY": { "type": "integer", "minimum": 0, "maximum": 100 } }, "minProperties": 1 }, "EventOperationsMediaEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsMediaRecord" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsMediaDeleteResult": { "type": "object", "additionalProperties": false, "required": [ "deleted", "cleanupPending" ], "properties": { "deleted": { "type": "boolean", "const": true }, "cleanupPending": { "type": "boolean" } } }, "EventOperationsMediaDeleteEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsMediaDeleteResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsBrandingInput": { "type": "object", "additionalProperties": false, "required": [ "theme" ], "properties": { "theme": { "$ref": "#/components/schemas/EventBrandingTheme" } } }, "EventOperationsBrandingResult": { "type": "object", "additionalProperties": false, "required": [ "theme" ], "properties": { "theme": { "$ref": "#/components/schemas/EventBrandingTheme" } } }, "EventOperationsBrandingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsBrandingResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsBrandingTemplateCreateInput": { "type": "object", "additionalProperties": false, "required": [ "name", "theme" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "theme": { "$ref": "#/components/schemas/EventBrandingTheme" } } }, "EventOperationsBrandingTemplateUpdateInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "theme": { "$ref": "#/components/schemas/EventBrandingTheme" } }, "minProperties": 1 }, "EventOperationsBrandingTemplateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsBrandingTemplate" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsDeletionResult": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } }, "EventOperationsDeletionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsDeletionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsMediaBinary": { "type": "string", "format": "binary" }, "EventOperationsSecretLink": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "eventId", "slug", "status", "last4", "expiresAt", "maxUses", "usageCount", "createdByUserId", "createdAt", "updatedAt", "revokedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 191 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "last4": { "type": "string", "pattern": "^[A-Za-z0-9_-]{4}$" }, "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "maxUses": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 500 }, { "type": "null" } ] }, "usageCount": { "type": "integer", "minimum": 0 }, "createdByUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "EventOperationsSecretLinkListResult": { "type": "object", "additionalProperties": false, "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/EventOperationsSecretLink" }, "maxItems": 100 } } }, "EventOperationsSecretLinkListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsSecretLinkListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsSecretLinkCreateInput": { "type": "object", "additionalProperties": false, "properties": { "expiresAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "maxUses": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 500 }, { "type": "null" } ] }, "replaceExisting": { "type": "boolean", "default": true } } }, "EventOperationsSecretLinkCreateResult": { "type": "object", "additionalProperties": false, "required": [ "link", "token", "url" ], "properties": { "link": { "$ref": "#/components/schemas/EventOperationsSecretLink" }, "token": { "type": "string", "minLength": 43, "maxLength": 43 }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" } } }, "EventOperationsSecretLinkCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsSecretLinkCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EventOperationsSecretLinkResult": { "type": "object", "additionalProperties": false, "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/EventOperationsSecretLink" } } }, "EventOperationsSecretLinkEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EventOperationsSecretLinkResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SupportCaseStatusInput": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, "expectedRevision": { "type": "integer", "minimum": 1 } } }, "SupportCaseListQuery": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] } } }, "AdminSupportCaseListQuery": { "type": "object", "additionalProperties": false, "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] } } }, "SupportCaseLifecycleEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "fromStatus", "toStatus", "actor", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "created", "customerReplied", "operatorReplied", "internalNoteAdded", "assigned", "statusChanged", "priorityChanged", "resolved", "reopened" ] }, "fromStatus": { "oneOf": [ { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, { "type": "null" } ] }, "toStatus": { "oneOf": [ { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, { "type": "null" } ] }, "actor": { "type": "object", "additionalProperties": false, "required": [ "kind", "displayName" ], "properties": { "kind": { "type": "string", "enum": [ "customer", "operator", "system" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "details": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "SupportCaseLifecycleView": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "customerId", "caseNumber", "subject", "status", "priority", "category", "assignedTo", "customer", "conversationThreadId", "responseDueAt", "firstResponseAt", "lastCustomerMessageAt", "lastOperatorResponseAt", "resolvedAt", "revision", "slaState", "summary", "lastActivityAt", "createdAt", "updatedAt", "events" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "customerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "caseNumber": { "type": "string", "minLength": 10, "maxLength": 32 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "category": { "type": "string", "enum": [ "technical", "billing", "account", "bookings", "events", "tickets", "general" ] }, "assignedTo": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "displayName" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 320 } } }, { "type": "null" } ] }, "customer": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "emailMasked" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 320 }, "emailMasked": { "type": "string", "minLength": 3, "maxLength": 320 } } }, { "type": "null" } ] }, "conversationThreadId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "responseDueAt": { "type": "string", "format": "date-time" }, "firstResponseAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastCustomerMessageAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastOperatorResponseAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "resolvedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1 }, "slaState": { "type": "string", "enum": [ "onTrack", "dueSoon", "overdue", "waitingOnCustomer", "resolved" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 10000 }, "lastActivityAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/SupportCaseLifecycleEvent" }, "maxItems": 250 } } }, "SupportCaseLifecycleList": { "type": "object", "additionalProperties": false, "required": [ "cases", "truncated" ], "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/SupportCaseLifecycleView" }, "maxItems": 250 }, "truncated": { "type": "boolean" } } }, "SupportCaseLifecycleListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SupportCaseLifecycleList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SupportCaseLifecycleDetail": { "type": "object", "additionalProperties": false, "required": [ "supportCase", "conversation" ], "properties": { "supportCase": { "$ref": "#/components/schemas/SupportCaseLifecycleView" }, "conversation": { "oneOf": [ { "$ref": "#/components/schemas/ConversationThread" }, { "type": "null" } ] } } }, "SupportCaseLifecycleEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SupportCaseLifecycleDetail" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerSupportCaseCreateInput": { "type": "object", "additionalProperties": false, "required": [ "category" ], "properties": { "category": { "type": "string", "enum": [ "technical", "billing", "account", "bookings", "events", "tickets", "general" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ], "default": "medium" } } }, "CustomerConversationCreateResult": { "type": "object", "additionalProperties": false, "required": [ "thread", "supportCase" ], "properties": { "thread": { "$ref": "#/components/schemas/ConversationThread" }, "supportCase": { "oneOf": [ { "$ref": "#/components/schemas/SupportCaseLifecycleView" }, { "type": "null" } ] } } }, "CustomerConversationCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerConversationCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncVerificationMethod": { "type": "string", "enum": [ "metaTag", "wellKnown", "dnsTxt" ] }, "WebsiteSyncVerificationStatus": { "type": "string", "enum": [ "pending", "verified", "failed", "expired", "revoked" ] }, "WebsiteSyncImportScope": { "type": "string", "enum": [ "structured", "richContent", "aiAssisted" ] }, "WebsiteSyncImportRunStatus": { "type": "string", "enum": [ "queued", "processing", "pendingReview", "applied", "failed", "cancelled", "reverted" ] }, "WebsiteSyncImportScheduleStatus": { "type": "string", "enum": [ "active", "paused" ] }, "WebsiteSyncImportFieldKind": { "type": "string", "enum": [ "location.name", "location.description", "location.address", "location.contact.phone", "location.contact.email", "location.contact.website", "calendar.availability", "events.drafts" ] }, "WebsiteSyncVerification": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "domain", "method", "status", "evidenceUrl", "lastHttpStatus", "failureCode", "attemptCount", "nextCheckAt", "expiresAt", "verifiedAt", "lastCheckedAt", "revokedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "domain": { "type": "string", "format": "uri", "maxLength": 2048 }, "method": { "$ref": "#/components/schemas/WebsiteSyncVerificationMethod" }, "status": { "$ref": "#/components/schemas/WebsiteSyncVerificationStatus" }, "evidenceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lastHttpStatus": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "nextCheckAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncImportConsent": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "scope", "legalBasis", "consentTextVersion", "grantedAt", "revokedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" }, "legalBasis": { "type": "string", "const": "consent" }, "consentTextVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "grantedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncJsonValue": { "oneOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WebsiteSyncJsonValue" } }, { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncJsonValue" } }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "WebsiteSyncImportField": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "label", "currentValue", "proposedValue", "sourceUrl", "confidence" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "$ref": "#/components/schemas/WebsiteSyncImportFieldKind" }, "label": { "type": "string", "minLength": 1, "maxLength": 240 }, "currentValue": { "anyOf": [ { "$ref": "#/components/schemas/WebsiteSyncJsonValue" }, { "type": "null" } ] }, "proposedValue": { "$ref": "#/components/schemas/WebsiteSyncJsonValue" }, "sourceUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "WebsiteSyncImportDiff": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "generatedAt", "fields" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-website-import-diff-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportField" }, "maxItems": 100 } } }, "WebsiteSyncImportRun": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "verificationId", "consentId", "scheduleId", "scope", "status", "sourceUrl", "crawledUrls", "proposedChanges", "selectedFieldIds", "sourceHash", "errorCode", "errorMessage", "attemptCount", "queuedAt", "startedAt", "reviewReadyAt", "appliedAt", "revertedAt", "failedAt", "cancelledAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "verificationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "consentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scheduleId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" }, "status": { "$ref": "#/components/schemas/WebsiteSyncImportRunStatus" }, "sourceUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "crawledUrls": { "type": "array", "items": { "type": "string", "format": "uri", "maxLength": 2048 }, "minItems": 0, "maxItems": 5, "uniqueItems": true }, "proposedChanges": { "anyOf": [ { "$ref": "#/components/schemas/WebsiteSyncImportDiff" }, { "type": "null" } ] }, "selectedFieldIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 0, "maxItems": 100, "uniqueItems": true }, "sourceHash": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "queuedAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reviewReadyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "appliedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revertedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncImportSchedule": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "locationId", "verificationId", "consentId", "scope", "status", "frequencyDays", "reminderLeadHours", "nextRunAt", "lastRunAt", "lastReminderAt", "optOutAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "verificationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "consentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" }, "status": { "$ref": "#/components/schemas/WebsiteSyncImportScheduleStatus" }, "frequencyDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "reminderLeadHours": { "type": "integer", "minimum": 0, "maximum": 168 }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastReminderAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "optOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncState": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "verifications", "consents", "runs", "schedules" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-website-sync-contract-v1" }, "verifications": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncVerification" }, "maxItems": 100 }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportConsent" }, "maxItems": 100 }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportRun" }, "maxItems": 100 }, "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportSchedule" }, "maxItems": 100 } } }, "WebsiteSyncStateQuery": { "type": "object", "additionalProperties": false, "required": [ "locationId" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "WebsiteSyncRunListQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 160 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "WebsiteSyncVerificationCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "domain", "method" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "domain": { "type": "string", "minLength": 1, "maxLength": 2048 }, "method": { "$ref": "#/components/schemas/WebsiteSyncVerificationMethod" } } }, "WebsiteSyncVerificationProof": { "type": "object", "additionalProperties": false, "required": [ "token", "placement", "value" ], "properties": { "token": { "type": "string", "pattern": "^vsm_verify_[A-Za-z0-9_-]{32}$", "writeOnly": true, "description": "Returned exactly once; only hash plus encrypted proof persist" }, "placement": { "type": "string", "minLength": 1, "maxLength": 4096 }, "value": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } } }, "WebsiteSyncVerificationCreateResult": { "type": "object", "additionalProperties": false, "required": [ "verification", "proof" ], "properties": { "verification": { "$ref": "#/components/schemas/WebsiteSyncVerification" }, "proof": { "$ref": "#/components/schemas/WebsiteSyncVerificationProof" } } }, "WebsiteSyncVerificationResult": { "type": "object", "additionalProperties": false, "required": [ "verification" ], "properties": { "verification": { "$ref": "#/components/schemas/WebsiteSyncVerification" } } }, "WebsiteSyncVerificationList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncVerification" }, "maxItems": 100 } } }, "WebsiteSyncConsentCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "scope" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" } } }, "WebsiteSyncConsentResult": { "type": "object", "additionalProperties": false, "required": [ "consent" ], "properties": { "consent": { "$ref": "#/components/schemas/WebsiteSyncImportConsent" } } }, "WebsiteSyncRunCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "verificationId", "consentId", "scope" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "verificationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "consentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" } } }, "WebsiteSyncRunApplyInput": { "type": "object", "additionalProperties": false, "required": [ "selectedFieldIds" ], "properties": { "selectedFieldIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 1, "maxItems": 100, "uniqueItems": true } } }, "WebsiteSyncRunResult": { "type": "object", "additionalProperties": false, "required": [ "run" ], "properties": { "run": { "$ref": "#/components/schemas/WebsiteSyncImportRun" } } }, "WebsiteSyncRunPage": { "type": "object", "additionalProperties": false, "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportRun" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } } }, "WebsiteSyncScheduleCreateInput": { "type": "object", "additionalProperties": false, "required": [ "locationId", "verificationId", "consentId", "scope", "frequencyDays", "reminderLeadHours", "nextRunAt" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "verificationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "consentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "$ref": "#/components/schemas/WebsiteSyncImportScope" }, "frequencyDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "reminderLeadHours": { "type": "integer", "minimum": 0, "maximum": 168 }, "nextRunAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncScheduleUpdateInput": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "status": { "$ref": "#/components/schemas/WebsiteSyncImportScheduleStatus" }, "frequencyDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "reminderLeadHours": { "type": "integer", "minimum": 0, "maximum": 168 }, "nextRunAt": { "type": "string", "format": "date-time" } } }, "WebsiteSyncScheduleResult": { "type": "object", "additionalProperties": false, "required": [ "schedule" ], "properties": { "schedule": { "$ref": "#/components/schemas/WebsiteSyncImportSchedule" } } }, "WebsiteSyncScheduleList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteSyncImportSchedule" }, "maxItems": 100 } } }, "WebsiteSyncStateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncVerificationCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncVerificationCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncVerificationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncVerificationResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncVerificationListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncVerificationList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncConsentEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncConsentResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncRunEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncRunResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncRunPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncRunPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncScheduleEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncScheduleResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WebsiteSyncScheduleListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebsiteSyncScheduleList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "VenueProfileWeekday": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "VenueProfileLifecycleStatus": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "VenueProfileVersionLifecycleStatus": { "type": "string", "enum": [ "draft", "published", "superseded" ] }, "VenueProfileAddress": { "type": "object", "additionalProperties": false, "required": [ "street", "postalCode", "city", "countryCode" ], "properties": { "street": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] }, "postalCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 0, "maxLength": 120 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } } }, "VenueProfileContact": { "type": "object", "additionalProperties": false, "required": [ "phone", "email", "websiteUrl" ], "properties": { "phone": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "email": { "oneOf": [ { "type": "string", "format": "email", "maxLength": 320 }, { "type": "null" } ] }, "websiteUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] } } }, "VenueProfileCoordinates": { "type": "object", "additionalProperties": false, "required": [ "latitude", "longitude" ], "properties": { "latitude": { "oneOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "oneOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } } }, "VenueProfileOpeningState": { "type": "object", "additionalProperties": false, "required": [ "status", "isOpen", "checkedAt", "timezone" ], "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] }, "isOpen": { "type": "boolean" }, "checkedAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "VenueProfileVersionSnapshot": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "revision", "status", "publishedAt", "updatedAt", "profile" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "version": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "status": { "$ref": "#/components/schemas/VenueProfileVersionLifecycleStatus" }, "publishedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "profile": { "$ref": "#/components/schemas/VenueProfileDraft" } } }, "VenueProfileLocationSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "status", "timezone" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "VenueProfileAdminState": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "updatedAt", "activeVersion", "draftVersion", "suggestedDraft" ], "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/VenueProfileLifecycleStatus" }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "activeVersion": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileVersionSnapshot" }, { "type": "null" } ] }, "draftVersion": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileVersionSnapshot" }, { "type": "null" } ] }, "suggestedDraft": { "$ref": "#/components/schemas/VenueProfileDraft" } } }, "VenueProfilePermissions": { "type": "object", "additionalProperties": false, "required": [ "canEdit", "canPublish" ], "properties": { "canEdit": { "type": "boolean" }, "canPublish": { "type": "boolean" } } }, "VenueProfileAdminEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VenueProfileAdminProjection" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicVenueProfile": { "allOf": [ { "$ref": "#/components/schemas/VenueProfileDraft" }, { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "locationSlug", "openingState", "configuredModules", "availableModules" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "openingState": { "$ref": "#/components/schemas/VenueProfileOpeningState" }, "configuredModules": { "type": "array", "maxItems": 4, "uniqueItems": true, "items": { "$ref": "#/components/schemas/VenueProfilePublicModule" } }, "availableModules": { "type": "array", "maxItems": 4, "uniqueItems": true, "items": { "$ref": "#/components/schemas/VenueProfilePublicModule" } } } } ] }, "VenueProfileModuleLink": { "type": "object", "additionalProperties": false, "required": [ "href", "label" ], "properties": { "href": { "type": "string", "minLength": 1, "maxLength": 2048 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "VenueProfileModuleMap": { "type": "object", "additionalProperties": false, "required": [ "booking", "events", "tickets", "coupons" ], "properties": { "booking": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileModuleLink" }, { "type": "null" } ] }, "events": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileModuleLink" }, { "type": "null" } ] }, "tickets": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileModuleLink" }, { "type": "null" } ] }, "coupons": { "oneOf": [ { "$ref": "#/components/schemas/VenueProfileModuleLink" }, { "type": "null" } ] } } }, "PublicVenueProfileEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicVenueProfileProjection" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicCalendarResult": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "location", "calendars", "page" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "location": { "$ref": "#/components/schemas/Location" }, "calendars": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Calendar" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" }, "effectiveFormOptions": { "$ref": "#/components/schemas/PublicBookingFormOptions" }, "publicFormLogoUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri" }, "customerTheme": { "$ref": "#/components/schemas/PublicBookingCustomerTheme" } } }, "PublicCalendarEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicCalendarResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicCalendarQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 1024 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "PublicAvailabilityQuery": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "date" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } } }, "PublicAvailabilitySlot": { "type": "object", "additionalProperties": false, "required": [ "id", "date", "startsAt", "endsAt", "label", "status", "capacity", "usedCapacity", "remainingCapacity" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "available", "full", "closed" ] }, "capacity": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "usedCapacity": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "remainingCapacity": { "type": "integer", "minimum": 0, "maximum": 1000000 } } }, "PublicCalendarAvailability": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "date", "timezone", "slots" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "date": { "type": "string", "format": "date" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "slots": { "type": "array", "maxItems": 24, "items": { "$ref": "#/components/schemas/PublicAvailabilitySlot" } } } }, "PublicCalendarAvailabilityEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicCalendarAvailability" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicBookingCreateInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "guestName", "partySize", "startsAt", "endsAt" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "guestFirstName": { "type": "string", "minLength": 1, "maxLength": 80, "description": "With bookingForm.contact.nameMode=split: required together with guestLastName. guestName stays required for compatibility; the server replaces it with \" \"." }, "guestLastName": { "type": "string", "minLength": 1, "maxLength": 80 }, "children": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "firstName" ], "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "description": "Child first names (no account). Requires contact.childBooking; each child becomes its own Booking with party size 1." }, "formEntry": { "type": "string", "enum": [ "location", "calendar" ], "default": "location", "description": "Entry whose form options apply: the location form or the direct calendar form." }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "attribution": { "type": "object", "additionalProperties": false, "properties": { "utmSource": { "type": "string", "maxLength": 200 }, "utmMedium": { "type": "string", "maxLength": 200 }, "utmCampaign": { "type": "string", "maxLength": 200 }, "landing": { "type": "string", "maxLength": 200 }, "referrerHost": { "type": "string", "maxLength": 253 } } }, "whatsappReminderOptIn": { "type": "object", "additionalProperties": false, "required": [ "textVersion", "locale" ], "properties": { "textVersion": { "type": "string", "enum": [ "booking-whatsapp-v2" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] } } } } }, "PublicBookingSelfServiceLink": { "type": "object", "additionalProperties": false, "required": [ "url", "expiresAt" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 4096, "readOnly": true, "x-vsm-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PublicBookingCreateResult": { "allOf": [ { "$ref": "#/components/schemas/BookingWorkflowResult" }, { "type": "object", "additionalProperties": false, "required": [], "properties": { "selfService": { "$ref": "#/components/schemas/PublicBookingSelfServiceLink" }, "childBookings": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "childFirstName", "booking" ], "properties": { "childFirstName": { "type": "string", "minLength": 1, "maxLength": 80 }, "booking": { "$ref": "#/components/schemas/Booking" }, "selfService": { "$ref": "#/components/schemas/PublicBookingSelfServiceLink" } } }, "description": "Present when children were registered: one Booking per child, in request order. `booking` is the first child's Booking." }, "whatsappReminder": { "type": "object", "additionalProperties": false, "required": [ "status", "consentTextVersion", "consentAt" ], "properties": { "status": { "type": "string", "enum": [ "active", "stopped", "unavailable" ] }, "consentTextVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "consentAt": { "type": "string", "format": "date-time" } } } } } ] }, "PublicBookingCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicBookingCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicWaitlistCreateInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "slotId", "guestName", "guestEmail" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "guestFirstName": { "type": "string", "minLength": 1, "maxLength": 80, "description": "With bookingForm.contact.nameMode=split: required together with guestLastName. guestName stays required for compatibility; the server replaces it with \" \"." }, "guestLastName": { "type": "string", "minLength": 1, "maxLength": 80 }, "children": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "firstName" ], "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "description": "Child first names (no account). Requires contact.childBooking; each child becomes its own Booking with party size 1." }, "formEntry": { "type": "string", "enum": [ "location", "calendar" ], "default": "location", "description": "Entry whose form options apply: the location form or the direct calendar form." }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "note": { "type": "string", "minLength": 0, "maxLength": 2000 } } }, "PublicWaitlistSlot": { "type": "object", "additionalProperties": false, "required": [ "id", "startsAt", "endsAt", "capacity", "reserved" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "capacity": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "reserved": { "type": "integer", "minimum": 0, "maximum": 1000000 } } }, "PublicWaitlistCreateResult": { "type": "object", "additionalProperties": false, "required": [ "status", "waitlistId", "position", "alreadyJoined", "slot" ], "properties": { "status": { "type": "string", "const": "accepted" }, "waitlistId": { "type": "string", "minLength": 1, "maxLength": 160 }, "position": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "alreadyJoined": { "type": "boolean" }, "manageToken": { "type": "string", "minLength": 32, "maxLength": 512, "readOnly": true, "x-vsm-sensitive": true }, "slot": { "$ref": "#/components/schemas/PublicWaitlistSlot" } } }, "PublicWaitlistCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicWaitlistCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicWaitlistCancelInput": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 512, "writeOnly": true } } }, "PublicWaitlistCancelResult": { "type": "object", "additionalProperties": false, "required": [ "status", "waitlistId" ], "properties": { "status": { "type": "string", "const": "cancelled" }, "waitlistId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "PublicWaitlistCancelEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicWaitlistCancelResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EdgeHealthStatus": { "type": "object", "additionalProperties": false, "required": [ "service", "status", "version", "timestamp" ], "properties": { "service": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "const": "ok" }, "version": { "type": "string", "minLength": 1, "maxLength": 64 }, "timestamp": { "type": "string", "format": "date-time" } } }, "EdgeHealthEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeHealthStatus" } } }, "EdgeRuntimeCheck": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "status", "required", "detail", "checkedAt" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "ok", "warning", "failed", "skipped" ] }, "required": { "type": "boolean" }, "detail": { "type": "string", "minLength": 1, "maxLength": 2000 }, "checkedAt": { "type": "string", "format": "date-time" } } }, "EdgeReadinessPublic": { "type": "object", "additionalProperties": false, "required": [ "service", "host", "version", "status", "strict", "timestamp" ], "properties": { "service": { "type": "string", "minLength": 1, "maxLength": 120 }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "version": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "ready", "degraded", "blocked" ] }, "strict": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } } }, "EdgeReadinessDetailed": { "type": "object", "additionalProperties": false, "required": [ "service", "host", "version", "status", "strict", "checks", "details", "timestamp" ], "properties": { "service": { "type": "string", "minLength": 1, "maxLength": 120 }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "version": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "ready", "degraded", "blocked" ] }, "strict": { "type": "boolean" }, "checks": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "ok", "warning", "failed", "skipped" ] } }, "details": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/EdgeRuntimeCheck" } }, "timestamp": { "type": "string", "format": "date-time" } } }, "EdgeReadinessResult": { "oneOf": [ { "$ref": "#/components/schemas/EdgeReadinessPublic" }, { "$ref": "#/components/schemas/EdgeReadinessDetailed" } ] }, "EdgeReadinessEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeReadinessResult" } } }, "EdgeUptimeResult": { "type": "object", "additionalProperties": false, "required": [ "status", "service", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ready", "degraded", "blocked" ] }, "service": { "type": "string", "minLength": 1, "maxLength": 120 }, "timestamp": { "type": "string", "format": "date-time" } } }, "EdgeOpenApiInfo": { "type": "object", "required": [ "title", "version" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "version": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": true }, "EdgeOpenApiDocument": { "type": "object", "required": [ "openapi", "info", "paths", "components" ], "properties": { "openapi": { "type": "string", "pattern": "^3\\.1(?:\\.|$)" }, "info": { "$ref": "#/components/schemas/EdgeOpenApiInfo" }, "paths": { "type": "object", "additionalProperties": true }, "components": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "EdgeEmbedScriptSource": { "type": "string", "contentMediaType": "application/javascript" }, "EdgeEmbedSession": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "origin", "mode", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "origin": { "type": "string", "format": "uri", "maxLength": 2048 }, "mode": { "type": "string", "enum": [ "calendar", "events", "tickets" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EdgeEmbedSessionCreateInput": { "type": "object", "additionalProperties": false, "required": [ "origin", "mode" ], "properties": { "origin": { "type": "string", "format": "uri", "maxLength": 2048 }, "mode": { "type": "string", "enum": [ "calendar", "events", "tickets" ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "EdgeEmbedSessionCreated": { "allOf": [ { "$ref": "#/components/schemas/EdgeEmbedSession" }, { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 24, "maxLength": 512, "readOnly": true, "x-vsm-sensitive": true } } } ] }, "EdgeEmbedSessionList": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/EdgeEmbedSession" } }, "page": { "$ref": "#/components/schemas/CursorPageInfo" } } }, "EdgeEmbedSessionListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeEmbedSessionList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EdgeEmbedSessionCreatedEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeEmbedSessionCreated" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "EdgeEmailUnsubscribeInput": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "email", "token" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "token": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true, "x-vsm-sensitive": true }, "scope": { "type": "string", "enum": [ "ALL", "KIND", "AUDIENCE" ], "default": "ALL" }, "kind": { "type": "string", "enum": [ "BOOKING_CONFIRMATION", "BOOKING_CANCELLATION", "BOOKING_REMINDER", "EVENT_ANNOUNCEMENT", "EVENT_CHANGED", "EVENT_CANCELLED", "TICKET_CONFIRMATION", "TICKET_TRANSFER", "TICKET_PROMOTION", "TEAM_INVITE", "MAGIC_LINK", "SECURITY_ALERT", "BILLING_NOTICE" ] }, "audience": { "type": "string", "enum": [ "DIRECT", "BOOKING_GUESTS", "TICKET_BUYERS", "EVENT_ATTENDEES", "TENANT_MEMBERS" ] } } }, "EdgeEmailUnsubscribeResult": { "type": "object", "additionalProperties": false, "required": [ "unsubscribed", "suppressionId", "scope" ], "properties": { "unsubscribed": { "type": "boolean", "const": true }, "suppressionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "EdgeEmailUnsubscribeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeEmailUnsubscribeResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventCreditTopUpInput": { "type": "object", "additionalProperties": false, "required": [ "amountMinor", "currency" ], "properties": { "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, "CustomerAccountEventCreditChargeTokenInput": { "type": "object", "additionalProperties": false, "required": [ "amountMinor", "currency" ], "properties": { "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ttlSeconds": { "type": "integer", "minimum": 30, "maximum": 300 } } }, "CustomerAccountEventCreditRefundInput": { "type": "object", "additionalProperties": false, "required": [ "currency" ], "properties": { "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "CustomerAccountEventCreditTransaction": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "customerId", "kind", "status", "amountMinor", "currency", "reference", "completedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "top_up", "charge", "charge_refund", "cash_refund", "adjustment", "chargeback", "reversal" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "partially_succeeded", "failed", "cancelled", "reversed" ] }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "reference": { "type": "string", "minLength": 1, "maxLength": 191 }, "failureCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerAccountEventCreditLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "transactionId", "eventId", "customerId", "kind", "deltaMinor", "currency", "occurredAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "transactionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "top_up", "charge", "cash_refund", "chargeback", "reversal" ] }, "deltaMinor": { "type": "integer" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "CustomerAccountEventCreditBalance": { "type": "object", "additionalProperties": false, "required": [ "availableMinor", "settledMinor", "reservedChargeMinor", "pendingTopUpMinor", "pendingRefundMinor", "deficitMinor", "lifetimeTopUpMinor", "lifetimeChargedMinor", "currency" ], "properties": { "availableMinor": { "type": "integer" }, "settledMinor": { "type": "integer" }, "reservedChargeMinor": { "type": "integer", "minimum": 0 }, "offlineReservedMinor": { "type": "integer", "minimum": 0 }, "pendingTopUpMinor": { "type": "integer", "minimum": 0 }, "pendingRefundMinor": { "type": "integer", "minimum": 0 }, "deficitMinor": { "type": "integer", "minimum": 0 }, "lifetimeTopUpMinor": { "type": "integer", "minimum": 0 }, "lifetimeChargedMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, "CustomerAccountEventCreditWallet": { "type": "object", "additionalProperties": false, "required": [ "version", "event", "customer", "balance", "ledger", "transactions" ], "properties": { "version": { "type": "string", "const": "vsm-event-credit-wallet-v1" }, "event": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug", "status", "currency", "topUpMinAmount", "topUpMaxAmount", "refundsEnabled", "refundAvailable", "endsAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 320 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "status": { "type": "string", "minLength": 1, "maxLength": 80 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "topUpMinAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "topUpMaxAmount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "refundsEnabled": { "type": "boolean" }, "refundAvailable": { "type": "boolean" }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "customer": { "type": "object", "additionalProperties": false, "required": [ "id", "displayName" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] } } }, "balance": { "$ref": "#/components/schemas/CustomerAccountEventCreditBalance" }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEventCreditLedgerEntry" }, "maxItems": 200 }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEventCreditTransaction" }, "maxItems": 200 } } }, "CustomerAccountEventCreditWalletListResult": { "type": "object", "additionalProperties": false, "required": [ "wallets" ], "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountEventCreditWallet" } } } }, "CustomerAccountEventCreditWalletListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventCreditWalletListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventCreditWalletResult": { "type": "object", "additionalProperties": false, "required": [ "wallet" ], "properties": { "wallet": { "$ref": "#/components/schemas/CustomerAccountEventCreditWallet" } } }, "CustomerAccountEventCreditWalletEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventCreditWalletResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventCreditPayment": { "type": "object", "additionalProperties": false, "required": [ "status", "requiresWebhook" ], "properties": { "status": { "type": "string", "minLength": 1, "maxLength": 80 }, "clientSecret": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "readOnly": true, "x-vsm-sensitive": true }, "requiresWebhook": { "type": "boolean" } } }, "CustomerAccountEventCreditPaymentPreparation": { "type": "object", "additionalProperties": false, "required": [ "transaction", "payment", "replayed" ], "properties": { "transaction": { "$ref": "#/components/schemas/CustomerAccountEventCreditTransaction" }, "payment": { "$ref": "#/components/schemas/CustomerAccountEventCreditPayment" }, "replayed": { "type": "boolean" } } }, "CustomerAccountEventCreditPaymentPreparationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventCreditPaymentPreparation" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventCreditChargeAuthorization": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "customerId", "amountMinor", "currency", "expiresAt", "tokenHint" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "tokenHint": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "CustomerAccountEventCreditChargeToken": { "type": "object", "additionalProperties": false, "required": [ "authorization", "token", "manualCode", "qrPayload" ], "properties": { "authorization": { "$ref": "#/components/schemas/CustomerAccountEventCreditChargeAuthorization" }, "token": { "type": "string", "minLength": 32, "maxLength": 256, "readOnly": true, "x-vsm-sensitive": true }, "manualCode": { "type": "string", "minLength": 8, "maxLength": 16, "readOnly": true, "x-vsm-sensitive": true }, "qrPayload": { "type": "string", "minLength": 1, "maxLength": 4096, "readOnly": true, "x-vsm-sensitive": true } } }, "CustomerAccountEventCreditChargeTokenEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventCreditChargeToken" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventCreditTransactionResult": { "type": "object", "additionalProperties": false, "required": [ "transaction", "replayed" ], "properties": { "transaction": { "$ref": "#/components/schemas/CustomerAccountEventCreditTransaction" }, "replayed": { "type": "boolean" } } }, "CustomerAccountEventCreditTransactionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventCreditTransactionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountNotificationPreferenceUpdateInput": { "type": "object", "additionalProperties": false, "required": [ "version", "updates" ], "properties": { "version": { "type": "string", "const": "vsm-notification-preferences-v1" }, "updates": { "type": "array", "minItems": 1, "maxItems": 9, "x-vsm-unique-by": [ "topic", "channel" ], "items": { "type": "object", "additionalProperties": false, "required": [ "topic", "channel", "enabled" ], "properties": { "topic": { "type": "string", "enum": [ "bookingReminders", "eventUpdates", "accountMessages" ] }, "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "enabled": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 0 } } } } } }, "CustomerAccountNotificationPreference": { "type": "object", "additionalProperties": false, "required": [ "topic", "channel", "enabled", "revision", "updatedAt" ], "properties": { "topic": { "type": "string", "enum": [ "bookingReminders", "eventUpdates", "accountMessages" ] }, "channel": { "type": "string", "enum": [ "email", "inApp", "push" ] }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 }, "updatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerAccountNotificationPreferences": { "type": "object", "additionalProperties": false, "required": [ "version", "preferences" ], "properties": { "version": { "type": "string", "const": "vsm-notification-preferences-v1" }, "preferences": { "type": "array", "minItems": 9, "maxItems": 9, "items": { "$ref": "#/components/schemas/CustomerAccountNotificationPreference" } } } }, "CustomerAccountPushDeviceRegistrationInput": { "type": "object", "additionalProperties": false, "required": [ "version", "installationId", "registrationToken", "platform", "displayName" ], "properties": { "version": { "type": "string", "const": "vsm-push-device-v1" }, "installationId": { "type": "string", "minLength": 16, "maxLength": 256, "writeOnly": true, "x-vsm-sensitive": true }, "registrationToken": { "type": "string", "minLength": 16, "maxLength": 4096, "writeOnly": true, "x-vsm-sensitive": true }, "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "appVersion": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "CustomerAccountPushDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "platform", "displayName", "appVersion", "status", "registeredAt", "lastSeenAt", "rotatedAt", "revokedAt", "invalidatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "appVersion": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "revoked", "invalid" ] }, "registeredAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "rotatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "invalidatedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerAccountNotificationSettings": { "type": "object", "additionalProperties": false, "required": [ "notificationPreferences", "pushDevices" ], "properties": { "notificationPreferences": { "$ref": "#/components/schemas/CustomerAccountNotificationPreferences" }, "pushDevices": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAccountPushDevice" }, "maxItems": 100 } } }, "CustomerAccountNotificationSettingsEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountNotificationSettings" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountNotificationPreferencesResult": { "type": "object", "additionalProperties": false, "required": [ "notificationPreferences" ], "properties": { "notificationPreferences": { "$ref": "#/components/schemas/CustomerAccountNotificationPreferences" } } }, "CustomerAccountNotificationPreferencesEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountNotificationPreferencesResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountPushDeviceResult": { "type": "object", "additionalProperties": false, "required": [ "device" ], "properties": { "device": { "$ref": "#/components/schemas/CustomerAccountPushDevice" } } }, "CustomerAccountPushDeviceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountPushDeviceResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountPushDeviceRevokeResult": { "type": "object", "additionalProperties": false, "required": [ "device", "providerRevoked" ], "properties": { "device": { "$ref": "#/components/schemas/CustomerAccountPushDevice" }, "providerRevoked": { "type": "boolean" } } }, "CustomerAccountPushDeviceRevokeEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountPushDeviceRevokeResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountEventAlertInteraction": { "type": "object", "additionalProperties": false, "required": [ "id", "openedAt", "clickedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "openedAt": { "type": "string", "format": "date-time" }, "clickedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerAccountEventAlertInteractionResult": { "type": "object", "additionalProperties": false, "required": [ "alert" ], "properties": { "alert": { "$ref": "#/components/schemas/CustomerAccountEventAlertInteraction" } } }, "CustomerAccountEventAlertInteractionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountEventAlertInteractionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AssistantTask": { "type": "string", "enum": [ "eventDescription", "bookingRules", "ticketStructure", "faqTooltips" ] }, "AssistantTone": { "type": "string", "enum": [ "professional", "friendly", "concise" ] }, "AssistantLength": { "type": "string", "enum": [ "short", "medium", "long" ] }, "AssistantTemplate": { "type": "object", "additionalProperties": false, "required": [ "task", "label", "prompts" ], "properties": { "task": { "$ref": "#/components/schemas/AssistantTask" }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "prompts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4000 }, "maxItems": 20 } } }, "AssistantTemplateList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantTemplate" }, "maxItems": 4 } } }, "AssistantTemplateListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantTemplateList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AssistantSuggestionInput": { "type": "object", "additionalProperties": false, "required": [ "task", "prompt" ], "properties": { "task": { "$ref": "#/components/schemas/AssistantTask" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "tone": { "$ref": "#/components/schemas/AssistantTone" }, "length": { "$ref": "#/components/schemas/AssistantLength" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "context": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ] } } } }, "AssistantSuggestion": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "bullets" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "bullets": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 100 } } }, "AssistantRun": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "task", "locale", "model", "provider", "status", "usedFallback", "tokensInput", "tokensOutput", "tokensTotal", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "userId": { "type": "string", "minLength": 1, "maxLength": 160 }, "task": { "$ref": "#/components/schemas/AssistantTask" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 160 }, "provider": { "type": "string", "enum": [ "openai", "fallback" ] }, "status": { "type": "string", "enum": [ "completed", "failed", "blocked", "rateLimited" ] }, "usedFallback": { "type": "boolean" }, "tokensInput": { "type": "integer", "minimum": 0 }, "tokensOutput": { "type": "integer", "minimum": 0 }, "tokensTotal": { "type": "integer", "minimum": 0 }, "promptHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "readOnly": true }, "inputSummary": { "type": "string", "minLength": 1, "maxLength": 500 }, "outputPreview": { "type": "string", "minLength": 1, "maxLength": 1000 }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 160 }, "errorMessage": { "type": "string", "minLength": 1, "maxLength": 1000 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ] } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AssistantUsageSummary": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "month", "limit", "tokensUsed", "remaining", "resetAt", "runs" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "limit": { "type": "integer", "minimum": 1 }, "tokensUsed": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "resetAt": { "type": "string", "format": "date-time" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantRun" }, "maxItems": 20 } } }, "AssistantUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantUsageSummary" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AssistantRateLimitDecision": { "type": "object", "additionalProperties": false, "required": [ "allowed", "count", "remaining", "resetAt" ], "properties": { "allowed": { "type": "boolean" }, "count": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "resetAt": { "type": "integer", "minimum": 0 } } }, "AssistantSuggestionResult": { "type": "object", "additionalProperties": false, "required": [ "run", "suggestions", "usage", "rateLimit" ], "properties": { "run": { "$ref": "#/components/schemas/AssistantRun" }, "suggestions": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "$ref": "#/components/schemas/AssistantSuggestion" } }, "usage": { "$ref": "#/components/schemas/AssistantUsageSummary" }, "rateLimit": { "$ref": "#/components/schemas/AssistantRateLimitDecision" } } }, "AssistantSuggestionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantSuggestionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OperatorCustomerConsentStatus": { "type": "string", "enum": [ "unknown", "granted", "denied" ] }, "OperatorCustomerListQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 160 }, "segment": { "type": "string", "minLength": 1, "maxLength": 80 }, "consent": { "$ref": "#/components/schemas/OperatorCustomerConsentStatus" } } }, "OperatorCustomerListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "customerKey", "primaryEmail", "segments", "marketingConsentStatus", "bookingCount", "ticketOrderCount", "emailMessageCount", "openSupportCaseCount", "totalSpendAmount", "currency", "firstActivityAt", "lastActivityAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerKey": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 }, "primaryPhone": { "type": "string", "minLength": 1, "maxLength": 64 }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 25 }, "marketingConsentStatus": { "type": "string", "enum": [ "unknown", "granted", "denied" ] }, "bookingCount": { "type": "integer", "minimum": 0 }, "ticketOrderCount": { "type": "integer", "minimum": 0 }, "emailMessageCount": { "type": "integer", "minimum": 0 }, "openSupportCaseCount": { "type": "integer", "minimum": 0 }, "totalSpendAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "firstActivityAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time" } } }, "OperatorCustomerPage": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] } } }, "OperatorCustomerListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorCustomerListItem" }, "maxItems": 100 }, "page": { "$ref": "#/components/schemas/OperatorCustomerPage" } } }, "OperatorCustomerListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OperatorCustomerListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OperatorCustomerContactPoint": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "value", "isPrimary" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "isPrimary": { "type": "boolean" }, "verifiedAt": { "type": "string", "format": "date-time" } } }, "OperatorCustomerDuplicateCandidate": { "type": "object", "additionalProperties": false, "required": [ "id", "primaryEmail", "reason" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 }, "reason": { "type": "string", "enum": [ "displayName", "phone" ] } } }, "OperatorCustomerTimelineItem": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "title", "detail", "timestamp", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "kind": { "type": "string", "enum": [ "booking", "ticketOrder", "email", "supportCase", "profile" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "detail": { "type": "string", "minLength": 0, "maxLength": 4000 }, "timestamp": { "type": "string", "format": "date-time" }, "href": { "type": "string", "minLength": 1, "maxLength": 2048 }, "status": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "OperatorCustomerProfile": { "allOf": [ { "$ref": "#/components/schemas/OperatorCustomerListItem" }, { "type": "object", "additionalProperties": false, "required": [ "contactPoints", "duplicateCandidates", "timeline" ], "properties": { "locale": { "type": "string", "enum": [ "de", "en" ] }, "marketingConsentAt": { "type": "string", "format": "date-time" }, "marketingConsentSource": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactPoints": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorCustomerContactPoint" }, "maxItems": 100 }, "duplicateCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorCustomerDuplicateCandidate" }, "maxItems": 10 }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorCustomerTimelineItem" }, "maxItems": 500 } } } ] }, "OperatorCustomerProfileResult": { "type": "object", "additionalProperties": false, "required": [ "profile" ], "properties": { "profile": { "$ref": "#/components/schemas/OperatorCustomerProfile" } } }, "OperatorCustomerProfileEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OperatorCustomerProfileResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "OperatorCustomerUpdateInput": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "primaryPhone": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 64 }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "enum": [ "de", "en" ] }, { "type": "null" } ] }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 25, "uniqueItems": true }, "marketingConsentStatus": { "$ref": "#/components/schemas/OperatorCustomerConsentStatus" }, "marketingConsentSource": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] } } }, "OperatorCustomerMergeInput": { "type": "object", "additionalProperties": false, "required": [ "targetCustomerId" ], "properties": { "targetCustomerId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "PlatformAdminFoundationCursorQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "PlatformAdminFoundationPage": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } } }, "PlatformAdminTenantSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "plan", "defaultLocale", "createdAt", "activeOverrides", "ownerStatus" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 2, "maxLength": 120 }, "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "defaultLocale": { "type": "string", "enum": [ "de", "en" ] }, "createdAt": { "type": "string", "format": "date-time" }, "activeOverrides": { "type": "array", "maxItems": 13, "items": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] } }, "ownerStatus": { "type": "string", "enum": [ "joined", "pending", "none" ] } } }, "PlatformAdminTenantListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminTenantSummary" } }, "page": { "$ref": "#/components/schemas/PlatformAdminFoundationPage" } } }, "PlatformAdminTenantListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminTenantListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminAuditEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "category", "severity", "action", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "actorEmailHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "actorDisplay": { "type": "string", "minLength": 1, "maxLength": 160 }, "category": { "type": "string", "enum": [ "auth", "billing", "booking", "ticketing", "admin", "security", "ops", "webhook", "assistant", "data" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 240 }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 160 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ipHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PlatformAdminAuditEventListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } }, "page": { "$ref": "#/components/schemas/PlatformAdminFoundationPage" } } }, "PlatformAdminAuditEventListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminAuditEventListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminFeatureOverride": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "feature", "status", "reason", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "expired" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 5000 }, "createdByUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PlatformAdminFeatureOverrideListResult": { "type": "object", "additionalProperties": false, "required": [ "items", "page" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminFeatureOverride" } }, "page": { "$ref": "#/components/schemas/PlatformAdminFoundationPage" } } }, "PlatformAdminFeatureOverrideListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminFeatureOverrideListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminSupportCaseCreateInput": { "type": "object", "additionalProperties": false, "required": [ "subject", "summary" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "subject": { "type": "string", "minLength": 2, "maxLength": 220 }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "requesterEmail": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "summary": { "type": "string", "minLength": 8, "maxLength": 10000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "PlatformAdminSupportCaseCreateResult": { "type": "object", "additionalProperties": false, "required": [ "supportCase", "auditEvent" ], "properties": { "supportCase": { "$ref": "#/components/schemas/PlatformAdminSupportCase" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "PlatformAdminSupportCaseCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminSupportCaseCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminFeatureOverrideCreateInput": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "feature", "reason" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "reason": { "type": "string", "minLength": 8, "maxLength": 5000 }, "expiresAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "PlatformAdminFeatureOverrideCreateResult": { "type": "object", "additionalProperties": false, "required": [ "override", "auditEvent", "tenantEntitlements" ], "properties": { "override": { "$ref": "#/components/schemas/PlatformAdminFeatureOverride" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" }, "tenantEntitlements": { "type": "array", "maxItems": 9, "items": { "$ref": "#/components/schemas/AuthEntitlement" } } } }, "PlatformAdminFeatureOverrideCreateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminFeatureOverrideCreateResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminRuntimeCheckStatus": { "type": "string", "enum": [ "ok", "warning", "failed", "skipped" ] }, "PlatformAdminRuntimeCheck": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "status", "required", "detail", "checkedAt" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 240 }, "status": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "required": { "type": "boolean" }, "detail": { "type": "string", "minLength": 0, "maxLength": 4000 }, "checkedAt": { "type": "string", "format": "date-time" } } }, "PlatformAdminReadinessSnapshot": { "type": "object", "additionalProperties": false, "required": [ "service", "host", "version", "status", "strict", "checks", "details", "timestamp" ], "properties": { "service": { "type": "string", "const": "vsmBooking" }, "host": { "type": "string", "const": "booking.vossmedien.de" }, "version": { "type": "string", "minLength": 1, "maxLength": 40 }, "status": { "type": "string", "enum": [ "ready", "degraded", "blocked" ] }, "strict": { "type": "boolean" }, "checks": { "type": "object", "additionalProperties": false, "required": [ "app", "database", "redis", "worker", "stripe", "mail", "sessionDevice", "mfa", "ticketPromotions", "ticketQueue", "pushDevices", "basicAuth" ], "properties": { "app": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "database": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "redis": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "worker": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "stripe": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "mail": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "sessionDevice": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "mfa": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "ticketPromotions": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "ticketQueue": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "pushDevices": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" }, "basicAuth": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheckStatus" } } }, "details": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/PlatformAdminRuntimeCheck" } }, "timestamp": { "type": "string", "format": "date-time" } } }, "PlatformAdminReleaseEvidence": { "type": "object", "additionalProperties": false, "required": [ "key", "expected", "actual", "status" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "expected": { "type": "string", "minLength": 0, "maxLength": 4000 }, "actual": { "type": "string", "minLength": 0, "maxLength": 4000 }, "status": { "type": "string", "enum": [ "passed", "warning", "blocked", "manual" ] }, "source": { "type": "string", "enum": [ "runtime", "env", "code", "manual", "manifest" ] }, "artifact": { "type": "string", "minLength": 1, "maxLength": 2048 }, "checkedAt": { "type": "string", "format": "date-time" }, "detail": { "type": "string", "minLength": 0, "maxLength": 4000 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PlatformAdminReleaseChecklistItem": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "category", "status", "source", "required", "automated", "blocksRelease", "detail", "remediation", "evidence" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 240 }, "category": { "type": "string", "enum": [ "admin", "security", "ops", "legal", "release" ] }, "status": { "type": "string", "enum": [ "passed", "warning", "blocked", "manual" ] }, "source": { "type": "string", "enum": [ "runtime", "env", "code", "manual", "manifest" ] }, "required": { "type": "boolean" }, "automated": { "type": "boolean" }, "blocksRelease": { "type": "boolean" }, "detail": { "type": "string", "minLength": 0, "maxLength": 10000 }, "remediation": { "type": "string", "minLength": 0, "maxLength": 10000 }, "evidence": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/PlatformAdminReleaseEvidence" } } } }, "PlatformAdminReleaseReadinessSummary": { "type": "object", "additionalProperties": false, "required": [ "total", "passed", "warning", "blocked", "manual", "releaseCandidate" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "passed": { "type": "integer", "minimum": 0 }, "warning": { "type": "integer", "minimum": 0 }, "blocked": { "type": "integer", "minimum": 0 }, "manual": { "type": "integer", "minimum": 0 }, "releaseCandidate": { "type": "boolean" } } }, "PlatformAdminReleaseReadinessReport": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "status", "releaseCandidate", "exitCode", "readiness", "checklist", "summary" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-release-readiness-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "release-candidate", "blocked", "manual-review" ] }, "releaseCandidate": { "type": "boolean" }, "exitCode": { "type": "integer", "enum": [ 0, 1 ] }, "readiness": { "$ref": "#/components/schemas/PlatformAdminReadinessSnapshot" }, "checklist": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminReleaseChecklistItem" } }, "summary": { "$ref": "#/components/schemas/PlatformAdminReleaseReadinessSummary" } } }, "PlatformAdminReleaseReadiness": { "type": "object", "additionalProperties": false, "required": [ "readiness", "checklist", "summary", "report" ], "properties": { "readiness": { "$ref": "#/components/schemas/PlatformAdminReadinessSnapshot" }, "checklist": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminReleaseChecklistItem" } }, "summary": { "$ref": "#/components/schemas/PlatformAdminReleaseReadinessSummary" }, "report": { "$ref": "#/components/schemas/PlatformAdminReleaseReadinessReport" } } }, "PlatformAdminReleaseReadinessEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminReleaseReadiness" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminOverviewMetrics": { "type": "object", "additionalProperties": false, "required": [ "tenants", "openSupportCases", "activeOverrides", "blockedReleaseItems" ], "properties": { "tenants": { "type": "integer", "minimum": 0 }, "openSupportCases": { "type": "integer", "minimum": 0 }, "activeOverrides": { "type": "integer", "minimum": 0 }, "blockedReleaseItems": { "type": "integer", "minimum": 0 } } }, "PlatformAdminOverview": { "type": "object", "additionalProperties": false, "required": [ "metrics", "tenants", "supportCases", "auditEvents", "featureOverrides", "release" ], "properties": { "metrics": { "$ref": "#/components/schemas/PlatformAdminOverviewMetrics" }, "tenants": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PlatformAdminTenantSummary" } }, "supportCases": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/PlatformAdminSupportCase" } }, "auditEvents": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } }, "featureOverrides": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/PlatformAdminFeatureOverride" } }, "release": { "$ref": "#/components/schemas/PlatformAdminReleaseReadiness" } } }, "PlatformAdminOverviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformAdminOverview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformAdminSupportCase": { "type": "object", "additionalProperties": false, "required": [ "id", "subject", "status", "priority", "lastActivityAt", "summary", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "caseNumber": { "type": "string", "minLength": 1, "maxLength": 32 }, "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "status": { "type": "string", "enum": [ "open", "inProgress", "waiting", "resolved" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "category": { "type": "string", "enum": [ "technical", "billing", "account", "bookings", "events", "tickets", "general" ] }, "requesterHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "assignedToUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "lastActivityAt": { "type": "string", "format": "date-time" }, "responseDueAt": { "type": "string", "format": "date-time" }, "firstResponseAt": { "type": "string", "format": "date-time" }, "lastCustomerMessageAt": { "type": "string", "format": "date-time" }, "lastOperatorResponseAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1 }, "slaState": { "type": "string", "enum": [ "onTrack", "dueSoon", "overdue", "waitingOnCustomer", "resolved" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 10000 }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AdminPlatformRoleAssignmentListQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "includeRevoked": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "role": { "type": "string", "enum": [ "superAdmin", "operationsAdmin", "supportAdmin", "readOnlyAuditor" ] }, "search": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "AdminPlatformRoleUser": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "displayName", "mfaEnabled" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "mfaEnabled": { "type": "boolean" } } }, "AdminPlatformRoleScope": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "global" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id", "name", "slug" ], "properties": { "type": { "type": "string", "const": "tenant" }, "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 } } } ] }, "AdminPlatformRoleAssignmentCurrent": { "type": "object", "additionalProperties": false, "required": [ "userId", "grants", "canManage" ], "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 191 }, "grants": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PlatformAdminRoleGrant" } }, "canManage": { "type": "boolean" } } }, "AdminPlatformConsolePermissions": { "type": "object", "additionalProperties": false, "required": [ "securityWrite", "qualityWrite", "credentialsWrite" ], "properties": { "securityWrite": { "type": "boolean" }, "qualityWrite": { "type": "boolean" }, "credentialsWrite": { "type": "boolean" } } }, "AdminPlatformConsoleAuditItem": { "type": "object", "additionalProperties": false, "required": [ "id", "category", "severity", "action", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "category": { "type": "string", "enum": [ "auth", "billing", "booking", "ticketing", "admin", "security", "ops", "webhook", "assistant", "data" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 240 }, "actorDisplay": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" } } }, "AdminPlatformConsoleAudit": { "type": "object", "additionalProperties": false, "required": [ "items", "truncated" ], "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminPlatformConsoleAuditItem" } }, "truncated": { "type": "boolean" } } }, "AdminPlatformSecuritySummary": { "type": "object", "additionalProperties": false, "required": [ "active", "revoked", "mfaProtected" ], "properties": { "active": { "type": "integer", "minimum": 0, "maximum": 50 }, "revoked": { "type": "integer", "minimum": 0, "maximum": 50 }, "mfaProtected": { "type": "integer", "minimum": 0, "maximum": 50 } } }, "AdminPlatformSecuritySession": { "type": "object", "additionalProperties": false, "required": [ "id", "account", "displayName", "deviceLabel", "mfaProtected", "current", "createdAt", "lastSeenAt", "expiresAt", "revokedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "account": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "deviceLabel": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240 }, { "type": "null" } ] }, "mfaProtected": { "type": "boolean" }, "current": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "AdminPlatformSecurityState": { "type": "object", "additionalProperties": false, "required": [ "persistence", "summary", "items" ], "properties": { "persistence": { "type": "string", "enum": [ "memory", "prisma" ] }, "summary": { "$ref": "#/components/schemas/AdminPlatformSecuritySummary" }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminPlatformSecuritySession" } } } }, "AdminPlatformQualitySummary": { "type": "object", "additionalProperties": false, "required": [ "ok", "warning", "critical" ], "properties": { "ok": { "type": "integer", "minimum": 0 }, "warning": { "type": "integer", "minimum": 0 }, "critical": { "type": "integer", "minimum": 0 } } }, "AdminPlatformQualityCheck": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "status", "count", "detail" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "minLength": 1, "maxLength": 240 }, "status": { "type": "string", "enum": [ "ok", "warning", "critical" ] }, "count": { "type": "integer", "minimum": 0 }, "detail": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "AdminPlatformQualityResult": { "type": "object", "additionalProperties": false, "required": [ "scope", "checkedAt", "summary", "checks" ], "properties": { "scope": { "type": "string", "enum": [ "exact", "bounded-preview" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/AdminPlatformQualitySummary" }, "checks": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/AdminPlatformQualityCheck" } } } }, "AdminPlatformProviderCredentialStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "configured", "missing", "source" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "type": "string", "minLength": 1, "maxLength": 160 }, "configured": { "type": "boolean" }, "missing": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "source": { "type": "string", "enum": [ "environment", "local-storage" ] } } }, "AdminPlatformConsoleTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "AdminPlatformCredentialProjection": { "type": "object", "additionalProperties": false, "required": [ "id", "tenant", "kind", "name", "scopes", "publicKeyPreview", "lastUsedAt", "revokedAt", "createdAt", "rotatable" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenant": { "$ref": "#/components/schemas/AdminPlatformConsoleTenant" }, "kind": { "type": "string", "enum": [ "apiKey", "embed", "webhook", "stripeConnect" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "scopes": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "publicKeyPreview": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "rotatable": { "type": "boolean" } } }, "AdminPlatformWebhookEndpointProjection": { "type": "object", "additionalProperties": false, "required": [ "id", "tenant", "targetOrigin", "active", "signingSecretStored", "lastTestedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenant": { "$ref": "#/components/schemas/AdminPlatformConsoleTenant" }, "targetOrigin": { "type": "string", "minLength": 1, "maxLength": 2048 }, "active": { "type": "boolean" }, "signingSecretStored": { "type": "boolean" }, "lastTestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "AdminPlatformCredentialState": { "type": "object", "additionalProperties": false, "required": [ "providerStatus", "deliveryControl", "items", "webhookEndpoints" ], "properties": { "deliveryControl": { "$ref": "#/components/schemas/DeliveryProviderControlSnapshot" }, "providerStatus": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AdminPlatformProviderCredentialStatus" } }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminPlatformCredentialProjection" } }, "webhookEndpoints": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminPlatformWebhookEndpointProjection" } } } }, "AdminWorkerQueueKey": { "type": "string", "enum": [ "mail", "seatHolds", "webhooks", "websiteSync", "stripeSync", "exports", "cleanup" ] }, "AdminWorkerScheduleId": { "type": "string", "enum": [ "workflow-events-process-pending", "mail-deliver-queued", "seat-holds-expire-stale", "webhooks-deliver-pending", "website-sync-process-pending", "event-credits-maintain", "ticket-finance-maintain", "ticket-payouts-reconcile", "ticket-transfers-expire", "ticket-promotions-maintain", "ticket-queues-maintain", "waitlist-maintain", "tenant-trials-expire", "privacy-erase-customer-accounts", "privacy-purge-expired-data", "loyalty-accrue-completed-bookings", "artist-metadata-sync", "event-alerts-process", "social-publishing-process", "google-business-sync-process", "holiday-refresh-propose", "event-media-cleanup", "exports-process-pending", "exports-cleanup-expired" ] }, "AdminWorkerCommandInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "AdminWorkerScheduleRunNowInput": { "type": "object", "additionalProperties": false, "required": [ "reason", "idempotencyKey" ], "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 500 }, "idempotencyKey": { "type": "string", "minLength": 16, "maxLength": 160 } } }, "AdminWorkerFailurePageQuery": { "type": "object", "additionalProperties": false, "required": [], "properties": { "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "AdminWorkerQueueCounts": { "type": "object", "additionalProperties": false, "required": [ "waiting", "waitingChildren", "active", "delayed", "prioritized", "completed", "failed", "paused" ], "properties": { "waiting": { "type": "integer", "minimum": 0 }, "waitingChildren": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "delayed": { "type": "integer", "minimum": 0 }, "prioritized": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "paused": { "type": "integer", "minimum": 0 } } }, "AdminWorkerHeartbeat": { "type": "object", "additionalProperties": false, "required": [ "status", "updatedAt", "queues" ], "properties": { "status": { "type": "string", "enum": [ "online", "stale", "offline" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queues": { "type": "array", "maxItems": 7, "items": { "type": "string", "minLength": 1, "maxLength": 191 } } } }, "AdminWorkerQueueTotals": { "type": "object", "additionalProperties": false, "required": [ "waiting", "waitingChildren", "active", "delayed", "prioritized", "completed", "failed", "paused", "queues", "pausedQueues" ], "properties": { "waiting": { "type": "integer", "minimum": 0 }, "waitingChildren": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "delayed": { "type": "integer", "minimum": 0 }, "prioritized": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "paused": { "type": "integer", "minimum": 0 }, "queues": { "type": "integer", "minimum": 0, "maximum": 7 }, "pausedQueues": { "type": "integer", "minimum": 0, "maximum": 7 } } }, "AdminWorkerQueueMetrics": { "type": "object", "additionalProperties": false, "required": [ "completed", "failed" ], "properties": { "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } }, "AdminWorkerQueueSummary": { "type": "object", "additionalProperties": false, "required": [ "key", "name", "purpose", "jobNames", "status", "counts", "metrics24h" ], "properties": { "key": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "name": { "type": "string", "minLength": 1, "maxLength": 191 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "jobNames": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "status": { "type": "string", "enum": [ "running", "paused" ] }, "counts": { "$ref": "#/components/schemas/AdminWorkerQueueCounts" }, "metrics24h": { "$ref": "#/components/schemas/AdminWorkerQueueMetrics" } } }, "AdminWorkerQueueOverviewData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "worker", "totals", "queues" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-worker-queue-ops-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "worker": { "$ref": "#/components/schemas/AdminWorkerHeartbeat" }, "totals": { "$ref": "#/components/schemas/AdminWorkerQueueTotals" }, "queues": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "$ref": "#/components/schemas/AdminWorkerQueueSummary" } } } }, "AdminWorkerQueueOverviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkerQueueOverviewData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminWorkerFailureQueue": { "type": "object", "additionalProperties": false, "required": [ "key", "name", "purpose" ], "properties": { "key": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "name": { "type": "string", "minLength": 1, "maxLength": 191 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "AdminWorkerFailureDetail": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "fingerprint" ], "properties": { "code": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "message": { "type": "string", "minLength": 1, "maxLength": 240 }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "AdminWorkerFailedJob": { "type": "object", "additionalProperties": false, "required": [ "id", "queueKey", "name", "state", "attemptsMade", "attemptsAllowed", "queuedAt", "processedAt", "failedAt", "failure", "dataKeys" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "queueKey": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "failed" }, "attemptsMade": { "type": "integer", "minimum": 0 }, "attemptsAllowed": { "type": "integer", "minimum": 1 }, "queuedAt": { "type": "string", "format": "date-time" }, "processedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failure": { "$ref": "#/components/schemas/AdminWorkerFailureDetail" }, "dataKeys": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 160 } } } }, "AdminWorkerFailedJobPageData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "queue", "offset", "limit", "total", "items" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-worker-queue-failures-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "queue": { "$ref": "#/components/schemas/AdminWorkerFailureQueue" }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "total": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminWorkerFailedJob" } } } }, "AdminWorkerFailedJobPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkerFailedJobPageData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminWorkerQueueCommandResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "command", "queueKey", "queueName", "jobId", "changed", "state", "completedAt" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-worker-queue-command-v1" }, "command": { "type": "string", "enum": [ "pause", "resume", "retry" ] }, "queueKey": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "queueName": { "type": "string", "minLength": 1, "maxLength": 191 }, "jobId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "changed": { "type": "boolean" }, "state": { "type": "string", "enum": [ "active", "completed", "delayed", "failed", "paused", "prioritized", "running", "unknown", "waiting", "waiting-children" ] }, "completedAt": { "type": "string", "format": "date-time" } } }, "AdminWorkerQueueCommandData": { "type": "object", "additionalProperties": false, "required": [ "result", "auditEvent" ], "properties": { "result": { "$ref": "#/components/schemas/AdminWorkerQueueCommandResult" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "AdminWorkerQueueCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkerQueueCommandData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminWorkerScheduleTotals": { "type": "object", "additionalProperties": false, "required": [ "schedules", "running", "paused", "missing", "drifted", "failedRuns", "catchUpAvailable" ], "properties": { "schedules": { "type": "integer", "minimum": 0, "maximum": 24 }, "running": { "type": "integer", "minimum": 0, "maximum": 24 }, "paused": { "type": "integer", "minimum": 0, "maximum": 24 }, "missing": { "type": "integer", "minimum": 0, "maximum": 24 }, "drifted": { "type": "integer", "minimum": 0, "maximum": 24 }, "failedRuns": { "type": "integer", "minimum": 0 }, "catchUpAvailable": { "type": "integer", "minimum": 0 } } }, "AdminWorkerScheduleCatchUp": { "type": "object", "additionalProperties": false, "required": [ "availableRuns", "maxRunsPerCommand", "maxLookbackMs" ], "properties": { "availableRuns": { "type": "integer", "minimum": 0 }, "maxRunsPerCommand": { "type": "integer", "minimum": 1 }, "maxLookbackMs": { "type": "integer", "minimum": 1 } } }, "AdminWorkerScheduleMetrics": { "type": "object", "additionalProperties": false, "required": [ "completed", "failed", "manualQueued", "catchUpQueued", "lastCompletedAt", "lastFailedAt", "lastScheduledFor", "lastDurationMs", "lastTrigger" ], "properties": { "completed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "manualQueued": { "type": "integer", "minimum": 0 }, "catchUpQueued": { "type": "integer", "minimum": 0 }, "lastCompletedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastFailedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScheduledFor": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDurationMs": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "lastTrigger": { "anyOf": [ { "type": "string", "enum": [ "scheduled", "manual", "catch-up" ] }, { "type": "null" } ] } } }, "AdminWorkerScheduleSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "queueKey", "queueName", "jobName", "purpose", "timezone", "status", "intervalMs", "nextRunAt", "catchUp", "metrics" ], "properties": { "id": { "$ref": "#/components/schemas/AdminWorkerScheduleId" }, "queueKey": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "queueName": { "type": "string", "minLength": 1, "maxLength": 191 }, "jobName": { "type": "string", "minLength": 1, "maxLength": 160 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "timezone": { "type": "string", "const": "UTC" }, "status": { "type": "string", "enum": [ "running", "paused", "missing", "drifted" ] }, "intervalMs": { "type": "integer", "minimum": 1 }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "catchUp": { "$ref": "#/components/schemas/AdminWorkerScheduleCatchUp" }, "metrics": { "$ref": "#/components/schemas/AdminWorkerScheduleMetrics" } } }, "AdminWorkerScheduleOverviewData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "contractVersion", "generatedAt", "totals", "schedules" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-worker-schedule-ops-v1" }, "contractVersion": { "type": "string", "const": "vsm-worker-schedule-contract-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "totals": { "$ref": "#/components/schemas/AdminWorkerScheduleTotals" }, "schedules": { "type": "array", "minItems": 24, "maxItems": 24, "items": { "$ref": "#/components/schemas/AdminWorkerScheduleSummary" } } } }, "AdminWorkerScheduleOverviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkerScheduleOverviewData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminWorkerScheduleCommandResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "command", "scheduleId", "queueKey", "queueName", "changed", "state", "queuedRuns", "jobIds", "completedAt" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-worker-schedule-command-v1" }, "command": { "type": "string", "enum": [ "pause", "resume", "run-now", "catch-up" ] }, "scheduleId": { "$ref": "#/components/schemas/AdminWorkerScheduleId" }, "queueKey": { "$ref": "#/components/schemas/AdminWorkerQueueKey" }, "queueName": { "type": "string", "minLength": 1, "maxLength": 191 }, "changed": { "type": "boolean" }, "state": { "type": "string", "enum": [ "running", "paused", "missing", "drifted" ] }, "queuedRuns": { "type": "integer", "minimum": 0, "maximum": 10 }, "jobIds": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "completedAt": { "type": "string", "format": "date-time" } } }, "AdminWorkerScheduleCommandData": { "type": "object", "additionalProperties": false, "required": [ "result", "auditEvent" ], "properties": { "result": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandResult" }, "auditEvent": { "$ref": "#/components/schemas/PlatformAdminAuditEvent" } } }, "AdminWorkerScheduleCommandEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkerScheduleCommandData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WorkspaceAggregateScalarRecord": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "WorkspaceAggregateLaunchCenterTenant": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name", "plan" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "slug": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "plan": { "type": "string", "enum": [ "base", "growth", "platform" ] } } }, "WorkspaceAggregateLaunchCenterSummary": { "type": "object", "additionalProperties": false, "required": [ "status", "score", "completedSteps", "totalSteps", "blockedSteps", "nextStepKey" ], "properties": { "status": { "type": "string", "enum": [ "ready", "needs_action", "blocked" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "completedSteps": { "type": "integer", "minimum": 0, "maximum": 9 }, "totalSteps": { "type": "integer", "minimum": 0, "maximum": 9 }, "blockedSteps": { "type": "integer", "minimum": 0, "maximum": 9 }, "nextStepKey": { "anyOf": [ { "type": "string", "enum": [ "business", "location", "calendar", "seatmap", "event", "tickets", "mail", "embed", "payment" ] }, { "type": "null" } ] } } }, "WorkspaceAggregateLaunchCenterPublicLinks": { "type": "object", "additionalProperties": false, "required": [ "booking", "firstEvent", "embedPreview" ], "properties": { "booking": { "type": "string", "minLength": 1, "maxLength": 2048 }, "firstEvent": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "null" } ] }, "embedPreview": { "type": "string", "minLength": 1, "maxLength": 2048 } } }, "WorkspaceAggregateLaunchCenterStep": { "type": "object", "additionalProperties": false, "required": [ "key", "status", "actionHref", "missing", "facts" ], "properties": { "key": { "type": "string", "enum": [ "business", "location", "calendar", "seatmap", "event", "tickets", "mail", "embed", "payment" ] }, "status": { "type": "string", "enum": [ "done", "needs_action", "blocked", "unavailable" ] }, "actionHref": { "type": "string", "minLength": 1, "maxLength": 2048 }, "feature": { "type": "string", "enum": [ "tenant.core", "calendar.booking", "seatmaps.studio", "ticketing.checkout", "embeds.website", "api.webhooks", "loyalty.programs", "events.credits", "assistant.llm", "acquisition.pipeline", "families.participants", "communication.sms", "communication.whatsapp" ] }, "missing": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 191 } }, "facts": { "$ref": "#/components/schemas/WorkspaceAggregateScalarRecord" } } }, "WorkspaceAggregateLaunchCenter": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "tenant", "summary", "publicLinks", "steps" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "tenant": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenterTenant" }, "summary": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenterSummary" }, "publicLinks": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenterPublicLinks" }, "steps": { "type": "array", "minItems": 9, "maxItems": 9, "items": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenterStep" } } } }, "WorkspaceAggregateLaunchCenterEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceAggregateLaunchCenter" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WorkspaceAggregateOperatorInboxSummary": { "type": "object", "additionalProperties": false, "required": [ "total", "critical", "high", "bookingRequests", "customerRequests", "ticketOrders", "mailIssues" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "critical": { "type": "integer", "minimum": 0 }, "high": { "type": "integer", "minimum": 0 }, "bookingRequests": { "type": "integer", "minimum": 0 }, "customerRequests": { "type": "integer", "minimum": 0 }, "ticketOrders": { "type": "integer", "minimum": 0 }, "mailIssues": { "type": "integer", "minimum": 0 }, "leadTasks": { "type": "integer", "minimum": 0 } } }, "WorkspaceAggregateOperatorInboxItem": { "type": "object", "additionalProperties": false, "required": [ "id", "source", "kind", "severity", "status", "title", "detail", "timestamp", "href", "actionLabel" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "source": { "type": "string", "enum": [ "booking", "customerRequest", "event", "mail", "ticketOrder", "leadTask" ] }, "kind": { "type": "string", "enum": [ "taskOverdue", "taskReassign", "taskPending", "bookingRequest", "customerCancel", "customerReschedule", "eventDraft", "mailIssue", "ticketOrder" ] }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "status": { "type": "string", "minLength": 1, "maxLength": 191 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "detail": { "type": "string", "minLength": 1, "maxLength": 2000 }, "timestamp": { "type": "string", "format": "date-time" }, "href": { "type": "string", "minLength": 1, "maxLength": 2048 }, "actionLabel": { "type": "string", "minLength": 1, "maxLength": 191 }, "metadata": { "$ref": "#/components/schemas/WorkspaceAggregateScalarRecord" } } }, "WorkspaceAggregateOperatorInbox": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "summary", "items" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/WorkspaceAggregateOperatorInboxSummary" }, "items": { "type": "array", "maxItems": 24, "items": { "$ref": "#/components/schemas/WorkspaceAggregateOperatorInboxItem" } }, "page": { "$ref": "#/components/schemas/WorkspaceAggregateOperatorInboxPage" } } }, "WorkspaceAggregateOperatorInboxEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceAggregateOperatorInbox" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WorkspaceAggregateTicketMetrics": { "type": "object", "additionalProperties": false, "required": [ "sold", "reserved", "revenueAmount", "currency", "checkedIn", "noShows", "validTickets", "openOrders" ], "properties": { "sold": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "revenueAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "checkedIn": { "type": "integer", "minimum": 0 }, "noShows": { "type": "integer", "minimum": 0 }, "validTickets": { "type": "integer", "minimum": 0 }, "openOrders": { "type": "integer", "minimum": 0 } } }, "WorkspaceAggregateTicketTypeSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "priceAmount", "currency", "sold", "reserved", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "minLength": 1, "maxLength": 5000 }, "priceAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "inventoryLimit": { "type": "integer", "minimum": 0 }, "sold": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } }, "WorkspaceAggregateTicketOfferingSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "status", "currency", "sold", "reserved", "revenueAmount", "ticketTypes" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "totalLimit": { "type": "integer", "minimum": 0 }, "sold": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "revenueAmount": { "type": "integer", "minimum": 0 }, "ticketTypes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAggregateTicketTypeSummary" } } } }, "WorkspaceAggregateTicketOrderSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "offeringId", "buyerDisplay", "status", "totalAmount", "currency", "quantity", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 191 }, "buyerDisplay": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "pending", "completed", "cancelled", "refunded", "failed" ] }, "totalAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "quantity": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } } }, "WorkspaceAggregateTicketEntrySummary": { "type": "object", "additionalProperties": false, "required": [ "id", "offeringId", "ticketNumber", "buyerDisplay", "ticketTypeName", "offeringTitle", "status", "issuedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 191 }, "ticketNumber": { "type": "string", "minLength": 1, "maxLength": 191 }, "buyerDisplay": { "type": "string", "minLength": 1, "maxLength": 500 }, "ticketTypeName": { "type": "string", "minLength": 1, "maxLength": 500 }, "offeringTitle": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "pending", "valid", "redeemed", "cancelled", "refunded", "disputed" ] }, "issuedAt": { "type": "string", "format": "date-time" }, "noShowAt": { "type": "string", "format": "date-time" }, "checkedInAt": { "type": "string", "format": "date-time" } } }, "WorkspaceAggregateTicketWorkspace": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "tenantId", "metrics", "offerings", "recentOrders", "entryQueue" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "metrics": { "$ref": "#/components/schemas/WorkspaceAggregateTicketMetrics" }, "offerings": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAggregateTicketOfferingSummary" } }, "recentOrders": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/WorkspaceAggregateTicketOrderSummary" } }, "entryQueue": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/WorkspaceAggregateTicketEntrySummary" } } } }, "WorkspaceAggregateTicketWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceAggregateTicketWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipProductKind": { "type": "string", "enum": [ "package", "recurring" ] }, "MembershipProductStatus": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "CustomerMembershipStatus": { "type": "string", "enum": [ "active", "paused", "cancelled", "expired" ] }, "MembershipLedgerEntryKind": { "type": "string", "enum": [ "grant", "use", "release", "adjustment", "renewal" ] }, "MembershipProductCreateInput": { "type": "object", "additionalProperties": false, "required": [ "title", "kind", "priceMinor", "currency" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "package", "recurring" ] }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 100, "uniqueItems": true }, "transferable": { "type": "boolean" }, "autoRenew": { "type": "boolean" } } }, "MembershipProductUpdateInput": { "type": "object", "additionalProperties": false, "required": [], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "package", "recurring" ] }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 100, "uniqueItems": true }, "transferable": { "type": "boolean" }, "autoRenew": { "type": "boolean" } }, "minProperties": 1 }, "MembershipProductMetrics": { "type": "object", "additionalProperties": false, "required": [ "assignments", "active", "expiringSoon" ], "properties": { "assignments": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "expiringSoon": { "type": "integer", "minimum": 0 } } }, "MembershipProduct": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "title", "description", "kind", "status", "includedUnits", "validityDays", "priceMinor", "currency", "serviceIds", "transferable", "autoRenew", "version", "activatedAt", "archivedAt", "createdAt", "updatedAt", "metrics" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "kind": { "$ref": "#/components/schemas/MembershipProductKind" }, "status": { "$ref": "#/components/schemas/MembershipProductStatus" }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 100, "uniqueItems": true }, "transferable": { "type": "boolean" }, "autoRenew": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0 }, "activatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metrics": { "$ref": "#/components/schemas/MembershipProductMetrics" } } }, "MembershipProductResult": { "type": "object", "additionalProperties": false, "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/MembershipProduct" } } }, "MembershipProductEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MembershipProductResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipProductListResult": { "type": "object", "additionalProperties": false, "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipProduct" }, "maxItems": 100 } } }, "MembershipProductListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MembershipProductListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipCustomerSummary": { "type": "object", "additionalProperties": false, "required": [ "displayName", "primaryEmail" ], "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 } } }, "MembershipAssignmentProductSummary": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "$ref": "#/components/schemas/MembershipProductKind" } } }, "MembershipLedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "membershipId", "productId", "customerId", "kind", "deltaUnits", "balanceAfter", "sourceType", "sourceId", "note", "occurredAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "membershipId": { "type": "string", "minLength": 1, "maxLength": 160 }, "productId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "$ref": "#/components/schemas/MembershipLedgerEntryKind" }, "deltaUnits": { "type": "integer", "minimum": -1000000, "maximum": 1000000 }, "balanceAfter": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "sourceType": { "type": "string", "minLength": 1, "maxLength": 80 }, "sourceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" } } }, "CustomerMembership": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "productId", "customerId", "customer", "product", "status", "effectiveStatus", "title", "includedUnits", "remainingUnits", "usedUnits", "priceMinor", "currency", "serviceIds", "transferable", "autoRenew", "startsAt", "endsAt", "version", "pausedAt", "cancelledAt", "createdAt", "updatedAt", "ledger" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "productId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customer": { "$ref": "#/components/schemas/MembershipCustomerSummary" }, "product": { "$ref": "#/components/schemas/MembershipAssignmentProductSummary" }, "status": { "$ref": "#/components/schemas/CustomerMembershipStatus" }, "effectiveStatus": { "$ref": "#/components/schemas/CustomerMembershipStatus" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "remainingUnits": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "usedUnits": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 100, "uniqueItems": true }, "transferable": { "type": "boolean" }, "autoRenew": { "type": "boolean" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 0 }, "pausedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipLedgerEntry" }, "maxItems": 50 } } }, "CustomerMembershipResult": { "type": "object", "additionalProperties": false, "required": [ "membership" ], "properties": { "membership": { "$ref": "#/components/schemas/CustomerMembership" } } }, "CustomerMembershipEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerMembershipResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerMembershipListResult": { "type": "object", "additionalProperties": false, "required": [ "memberships" ], "properties": { "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMembership" }, "maxItems": 500 } } }, "CustomerMembershipListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerMembershipListResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerMembershipCreateInput": { "type": "object", "additionalProperties": false, "required": [ "productId", "customerId" ], "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 160 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "CustomerMembershipAdjustmentInput": { "type": "object", "additionalProperties": false, "required": [ "deltaUnits", "note" ], "properties": { "deltaUnits": { "type": "integer", "minimum": -1000000, "maximum": 1000000, "not": { "const": 0 } }, "note": { "type": "string", "minLength": 3, "maxLength": 500 } } }, "BookingMembershipApplyInput": { "type": "object", "additionalProperties": false, "required": [ "membershipId" ], "properties": { "membershipId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "BookingMembershipApplyResult": { "type": "object", "additionalProperties": false, "required": [ "applied", "units", "deduplicated", "membership" ], "properties": { "applied": { "type": "boolean", "const": true }, "units": { "type": "integer", "minimum": 1, "maximum": 1000 }, "deduplicated": { "type": "boolean" }, "membership": { "$ref": "#/components/schemas/CustomerMembership" } } }, "BookingMembershipApplyEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingMembershipApplyResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingMembershipReleaseResult": { "type": "object", "additionalProperties": false, "required": [ "released", "membershipId", "units", "deduplicated" ], "properties": { "released": { "type": "boolean", "const": true }, "membershipId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "units": { "type": "integer", "minimum": 0, "maximum": 1000 }, "deduplicated": { "type": "boolean" }, "membership": { "$ref": "#/components/schemas/CustomerMembership" } } }, "BookingMembershipReleaseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingMembershipReleaseResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipSubscriptionStatus": { "type": "string", "enum": [ "pending", "active", "past_due", "paused", "cancelled", "expired" ] }, "MembershipInvoiceStatus": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "MembershipBillingOffer": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "includedUnits", "validityDays", "priceMinor", "currency", "serviceIds", "transferable" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 5000 }, { "type": "null" } ] }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "maxItems": 100, "uniqueItems": true }, "transferable": { "type": "boolean" } } }, "CustomerMembershipSubscription": { "type": "object", "additionalProperties": false, "required": [ "id", "productId", "membershipId", "status", "title", "includedUnits", "priceMinor", "currency", "cancelAtPeriodEnd", "currentPeriodStart", "currentPeriodEnd", "lastPaidAt", "cancelledAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "productId": { "type": "string", "minLength": 1, "maxLength": 160 }, "membershipId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/MembershipSubscriptionStatus" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "includedUnits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "priceMinor": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "cancelAtPeriodEnd": { "type": "boolean" }, "currentPeriodStart": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "currentPeriodEnd": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastPaidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerMembershipInvoice": { "type": "object", "additionalProperties": false, "required": [ "id", "subscriptionId", "membershipId", "status", "number", "amountDueMinor", "amountPaidMinor", "currency", "billingReason", "hostedInvoiceUrl", "invoicePdfUrl", "periodStart", "periodEnd", "paidAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "membershipId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/MembershipInvoiceStatus" }, "number": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "amountDueMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "amountPaidMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "billingReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hostedInvoiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "invoicePdfUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "periodStart": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CustomerMembershipBillingOverviewResult": { "type": "object", "additionalProperties": false, "required": [ "memberships", "offers", "subscriptions", "invoices" ], "properties": { "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMembership" }, "maxItems": 500 }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipBillingOffer" }, "maxItems": 100 }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMembershipSubscription" }, "maxItems": 100 }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMembershipInvoice" }, "maxItems": 100 } } }, "CustomerMembershipBillingOverviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerMembershipBillingOverviewResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipCheckoutResult": { "type": "object", "additionalProperties": false, "required": [ "checkout", "subscriptionId", "replayed" ], "properties": { "checkout": { "type": "object", "additionalProperties": false, "required": [ "id", "url", "requiresWebhookFulfillment" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "format": "uri" }, "requiresWebhookFulfillment": { "type": "boolean", "const": true } } }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "replayed": { "type": "boolean" } } }, "MembershipCheckoutEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MembershipCheckoutResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "MembershipBillingPortalResult": { "type": "object", "additionalProperties": false, "required": [ "portal" ], "properties": { "portal": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } }, "MembershipBillingPortalEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MembershipBillingPortalResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformDocumentCategory": { "type": "string", "enum": [ "terms", "privacy", "security", "operations", "product" ] }, "PlatformDocumentCopy": { "type": "object", "additionalProperties": false, "required": [ "title", "summary", "body" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 } } }, "PlatformDocumentLocalizedCopy": { "type": "object", "additionalProperties": false, "required": [ "de", "en" ], "properties": { "de": { "$ref": "#/components/schemas/PlatformDocumentCopy" }, "en": { "$ref": "#/components/schemas/PlatformDocumentCopy" } } }, "PlatformDocumentAudience": { "type": "object", "additionalProperties": false, "required": [ "all", "tenantIds", "plans", "roles" ], "properties": { "all": { "type": "boolean" }, "tenantIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 191 }, "maxItems": 100, "uniqueItems": true }, "plans": { "type": "array", "items": { "type": "string", "enum": [ "base", "growth", "platform" ] }, "maxItems": 3, "uniqueItems": true }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "manager", "staff" ] }, "maxItems": 3, "uniqueItems": true } } }, "PlatformDocumentDraft": { "type": "object", "additionalProperties": false, "required": [ "copy", "acknowledgementRequired", "audience", "effectiveAt" ], "properties": { "copy": { "$ref": "#/components/schemas/PlatformDocumentLocalizedCopy" }, "acknowledgementRequired": { "type": "boolean" }, "audience": { "$ref": "#/components/schemas/PlatformDocumentAudience" }, "effectiveAt": { "type": "string", "format": "date-time" } } }, "PlatformDocumentRevision": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "revision", "status", "copy", "contentHash", "acknowledgementRequired", "audience", "effectiveAt", "publishedAt", "supersededAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "version": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "published", "superseded" ] }, "copy": { "$ref": "#/components/schemas/PlatformDocumentLocalizedCopy" }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "minLength": 64, "maxLength": 64 }, "acknowledgementRequired": { "type": "boolean" }, "audience": { "$ref": "#/components/schemas/PlatformDocumentAudience" }, "effectiveAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersededAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PlatformDocumentReceiptSummary": { "type": "object", "additionalProperties": false, "required": [ "total", "opened", "acknowledged", "outstanding" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "opened": { "type": "integer", "minimum": 0 }, "acknowledged": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 } } }, "PlatformDocument": { "type": "object", "additionalProperties": false, "required": [ "id", "key", "category", "status", "archivedAt", "createdAt", "updatedAt", "draft", "published", "history", "receiptSummary" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "category": { "$ref": "#/components/schemas/PlatformDocumentCategory" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "draft": { "anyOf": [ { "$ref": "#/components/schemas/PlatformDocumentRevision" }, { "type": "null" } ] }, "published": { "anyOf": [ { "$ref": "#/components/schemas/PlatformDocumentRevision" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDocumentRevision" }, "maxItems": 1000, "uniqueItems": true }, "receiptSummary": { "$ref": "#/components/schemas/PlatformDocumentReceiptSummary" } } }, "PlatformDocumentAdminSummary": { "type": "object", "additionalProperties": false, "required": [ "documents", "drafts", "published", "outstandingAcknowledgements" ], "properties": { "documents": { "type": "integer", "minimum": 0 }, "drafts": { "type": "integer", "minimum": 0 }, "published": { "type": "integer", "minimum": 0 }, "outstandingAcknowledgements": { "type": "integer", "minimum": 0 } } }, "PlatformDocumentAdminState": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "summary", "documents" ], "properties": { "schemaVersion": { "const": "vsm-platform-documents-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/PlatformDocumentAdminSummary" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDocument" }, "maxItems": 1000, "uniqueItems": true } } }, "PlatformDocumentCreateInput": { "type": "object", "additionalProperties": false, "required": [ "key", "category", "document" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "category": { "$ref": "#/components/schemas/PlatformDocumentCategory" }, "document": { "$ref": "#/components/schemas/PlatformDocumentDraft" } } }, "PlatformDocumentRevisionCreateInput": { "type": "object", "additionalProperties": false, "required": [ "document" ], "properties": { "document": { "$ref": "#/components/schemas/PlatformDocumentDraft" } } }, "PlatformDocumentDraftSaveInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "document" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "document": { "$ref": "#/components/schemas/PlatformDocumentDraft" } } }, "PlatformDocumentPublishInput": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "expectedRevision" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "expectedRevision": { "type": "integer", "minimum": 1 } } }, "PlatformDocumentArchiveInput": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "PlatformDocumentOperatorItem": { "type": "object", "additionalProperties": false, "required": [ "id", "documentId", "key", "category", "version", "title", "summary", "body", "locale", "acknowledgementRequired", "effectiveAt", "publishedAt", "openedAt", "acknowledgedAt", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "documentId": { "type": "string", "minLength": 1, "maxLength": 191 }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "category": { "$ref": "#/components/schemas/PlatformDocumentCategory" }, "version": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "acknowledgementRequired": { "type": "boolean" }, "effectiveAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" }, "openedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "acknowledgedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unread", "opened", "acknowledged" ] } } }, "PlatformDocumentOperatorSummary": { "type": "object", "additionalProperties": false, "required": [ "total", "unread", "acknowledgementRequired", "acknowledged" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "unread": { "type": "integer", "minimum": 0 }, "acknowledgementRequired": { "type": "integer", "minimum": 0 }, "acknowledged": { "type": "integer", "minimum": 0 } } }, "PlatformDocumentOperatorState": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "summary", "documents" ], "properties": { "schemaVersion": { "const": "vsm-platform-documents-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/PlatformDocumentOperatorSummary" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDocumentOperatorItem" }, "maxItems": 5000, "uniqueItems": true } } }, "PlatformDocumentAdminEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformDocumentAdminState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PlatformDocumentOperatorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformDocumentOperatorState" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "NativeHandoffAction": { "type": "string", "enum": [ "profile", "booking", "event" ] }, "NativeHandoffEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "title" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "slug": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 220 } } }, "NativeHandoffTarget": { "type": "object", "additionalProperties": false, "required": [ "id", "action", "title", "invocationUrl", "fallbackUrl" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 240 }, "action": { "$ref": "#/components/schemas/NativeHandoffAction" }, "title": { "type": "string", "minLength": 1, "maxLength": 220 }, "invocationUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 }, "fallbackUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 }, "event": { "$ref": "#/components/schemas/NativeHandoffEvent" } } }, "NativeHandoffLocation": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "slug": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "NativeHandoffReadiness": { "type": "object", "additionalProperties": false, "required": [ "profile", "booking", "eventCount", "appClipAssociation" ], "properties": { "profile": { "type": "boolean" }, "booking": { "type": "boolean" }, "eventCount": { "type": "integer", "minimum": 0, "maximum": 500 }, "appClipAssociation": { "type": "boolean" } } }, "NativeHandoffProjection": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "location", "targets", "readiness" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-native-handoff-contract-v1" }, "location": { "$ref": "#/components/schemas/NativeHandoffLocation" }, "targets": { "type": "array", "maxItems": 502, "items": { "$ref": "#/components/schemas/NativeHandoffTarget" } }, "readiness": { "$ref": "#/components/schemas/NativeHandoffReadiness" } } }, "NativeHandoffProjectionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/NativeHandoffProjection" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthProviderState": { "type": "object", "additionalProperties": false, "required": [ "provider", "enabled" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple" ] }, "enabled": { "type": "boolean" } } }, "AuthOAuthProviderInventoryData": { "type": "object", "additionalProperties": false, "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthOAuthProviderState" }, "minItems": 2, "maxItems": 2 } } }, "AuthOAuthAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "email", "displayName", "avatarUrl", "linkedAt", "lastAuthenticatedAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "google", "apple" ] }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "linkedAt": { "type": "string", "format": "date-time" }, "lastAuthenticatedAt": { "type": "string", "format": "date-time" } } }, "AuthOAuthAccountInventoryData": { "type": "object", "additionalProperties": false, "required": [ "providers", "accounts" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AuthOAuthProviderState" }, "minItems": 2, "maxItems": 2 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AuthOAuthAccount" }, "maxItems": 2 } } }, "AuthOAuthLinkRequestData": { "type": "object", "additionalProperties": false, "required": [ "provider", "email", "displayName", "avatarUrl", "expiresAt" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple" ] }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "AuthOAuthUnlinkData": { "type": "object", "additionalProperties": false, "required": [ "unlinked", "provider" ], "properties": { "unlinked": { "type": "boolean", "enum": [ true ] }, "provider": { "type": "string", "enum": [ "google", "apple" ] } } }, "AuthOAuthRejectData": { "type": "object", "additionalProperties": false, "required": [ "rejected" ], "properties": { "rejected": { "type": "boolean", "enum": [ true ] } } }, "AuthOAuthProviderInventoryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthProviderInventoryData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthAccountInventoryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthAccountInventoryData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthAccountEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthAccount" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthLinkRequestEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthLinkRequestData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthUnlinkEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthUnlinkData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AuthOAuthRejectEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthOAuthRejectData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "LoyaltyProgressionLevelInput": { "type": "object", "additionalProperties": false, "required": [ "title", "minimumLifetimePoints", "benefitDescription" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "minimumLifetimePoints": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "benefitDescription": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "LoyaltyProgressionBadgeInput": { "type": "object", "additionalProperties": false, "required": [ "code", "title", "description" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "icon": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "LoyaltyProgressionChallengeInput": { "type": "object", "additionalProperties": false, "required": [ "title", "description", "metric", "target", "rewardPoints", "status" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "metric": { "type": "string", "enum": [ "bookingsCompleted", "ticketsRedeemed", "referralsCompleted", "pointsEarned" ] }, "target": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "rewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "rewardBadgeCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "LoyaltyProgressionReferralCampaignInput": { "type": "object", "additionalProperties": false, "required": [ "title", "advocateRewardPoints", "referredRewardPoints", "maxRewardsPerAdvocate", "status" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "advocateRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "referredRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "maxRewardsPerAdvocate": { "type": "integer", "minimum": 1, "maximum": 10000 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "LoyaltyProgressionConfigInput": { "type": "object", "additionalProperties": false, "required": [ "levels", "badges", "challenges" ], "properties": { "levels": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionLevelInput" }, "maxItems": 25 }, "badges": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionBadgeInput" }, "maxItems": 50 }, "challenges": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionChallengeInput" }, "maxItems": 50 }, "referralCampaign": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionReferralCampaignInput" }, { "type": "null" } ] } } }, "LoyaltyProgressionLevel": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "minimumLifetimePoints", "benefitDescription", "revision" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "minimumLifetimePoints": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "benefitDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "revision": { "type": "integer", "minimum": 1 } } }, "LoyaltyProgressionBadge": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "title", "description", "icon" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": "string", "minLength": 1, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "icon": { "type": "string", "minLength": 1, "maxLength": 80 }, "earned": { "type": "boolean" } } }, "LoyaltyProgressionChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "metric", "target", "rewardPoints", "rewardBadgeCode", "status", "validFrom", "validUntil", "completedAt", "rewardGrantedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "metric": { "type": "string", "enum": [ "bookings_completed", "tickets_redeemed", "referrals_completed", "points_earned" ] }, "target": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "rewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "rewardBadgeCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "progress": { "type": "integer", "minimum": 0 }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rewardGrantedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "LoyaltyReferral": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "campaignId", "advocateCustomerId", "referredCustomerId", "codeHint", "status", "expiresAt", "claimedAt", "qualifiedAt", "rewardedAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "programId": { "type": "string", "minLength": 1, "maxLength": 160 }, "campaignId": { "type": "string", "minLength": 1, "maxLength": 160 }, "advocateCustomerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "referredCustomerId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "codeHint": { "type": "string", "minLength": 1, "maxLength": 16 }, "status": { "type": "string", "enum": [ "invited", "claimed", "qualified", "rewarded", "expired", "rejected" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "claimedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qualifiedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rewardedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "LoyaltyProgressionReferralCampaign": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "advocateRewardPoints", "referredRewardPoints", "maxRewardsPerAdvocate", "status", "validFrom", "validUntil", "revision" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "advocateRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "referredRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "maxRewardsPerAdvocate": { "type": "integer", "minimum": 1, "maximum": 10000 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "validFrom": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "validUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "integer", "minimum": 1 }, "referrals": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyReferral" }, "maxItems": 50 } } }, "LoyaltyProgressionCustomerLevel": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "benefitDescription", "minimumLifetimePoints" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "benefitDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumLifetimePoints": { "type": "integer", "minimum": 0, "maximum": 10000000 } } }, "LoyaltyProgressionNextLevel": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "minimumLifetimePoints", "remainingPoints" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "minimumLifetimePoints": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "remainingPoints": { "type": "integer", "minimum": 0, "maximum": 10000000 } } }, "LoyaltyProgressionCustomer": { "type": "object", "additionalProperties": false, "required": [ "wallet", "currentLevel", "nextLevel" ], "properties": { "wallet": { "type": "object", "additionalProperties": false, "required": [ "balance", "lifetimeEarned", "lifetimeRedeemed" ], "properties": { "balance": { "type": "integer", "minimum": 0 }, "lifetimeEarned": { "type": "integer", "minimum": 0 }, "lifetimeRedeemed": { "type": "integer", "minimum": 0 } } }, "currentLevel": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionCustomerLevel" }, { "type": "null" } ] }, "nextLevel": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionNextLevel" }, { "type": "null" } ] } } }, "LoyaltyProgression": { "type": "object", "additionalProperties": false, "required": [ "version", "program", "metrics", "levels", "badges", "challenges", "referralCampaign", "customer" ], "properties": { "version": { "type": "string", "const": "vsm-loyalty-progression-v1" }, "program": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "status", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "metrics": { "type": "object", "additionalProperties": false, "required": [ "participants", "badgeAwards", "challengeParticipants", "referrals" ], "properties": { "participants": { "type": "integer", "minimum": 0 }, "badgeAwards": { "type": "integer", "minimum": 0 }, "challengeParticipants": { "type": "integer", "minimum": 0 }, "referrals": { "type": "integer", "minimum": 0 } } }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionLevel" }, "maxItems": 25 }, "badges": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionBadge" }, "maxItems": 50 }, "challenges": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgressionChallenge" }, "maxItems": 50 }, "referralCampaign": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionReferralCampaign" }, { "type": "null" } ] }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionCustomer" }, { "type": "null" } ] } } }, "LoyaltyProgressionResult": { "type": "object", "additionalProperties": false, "required": [ "progression" ], "properties": { "progression": { "$ref": "#/components/schemas/LoyaltyProgression" } } }, "LoyaltyProgressionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/LoyaltyProgressionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerLoyaltyProgressionBadge": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "title", "description", "icon", "earned" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "code": { "type": "string", "minLength": 1, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "icon": { "type": "string", "minLength": 1, "maxLength": 80 }, "earned": { "type": "boolean" } } }, "CustomerLoyaltyProgressionChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "metric", "target", "rewardPoints", "rewardBadgeCode", "status", "progress", "completedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "metric": { "type": "string", "enum": [ "bookings_completed", "tickets_redeemed", "referrals_completed", "points_earned" ] }, "target": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "rewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "rewardBadgeCode": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "progress": { "type": "integer", "minimum": 0 }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerLoyaltyReferral": { "type": "object", "additionalProperties": false, "required": [ "id", "codeHint", "role", "status", "expiresAt", "claimedAt", "rewardedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "codeHint": { "type": "string", "minLength": 1, "maxLength": 16 }, "role": { "type": "string", "enum": [ "advocate", "referred" ] }, "status": { "type": "string", "enum": [ "invited", "claimed", "qualified", "rewarded", "expired", "rejected" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "claimedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rewardedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CustomerLoyaltyReferralCampaign": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "advocateRewardPoints", "referredRewardPoints", "status", "referrals" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "advocateRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "referredRewardPoints": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "referrals": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyReferral" }, "maxItems": 50 } } }, "CustomerLoyaltyProgression": { "type": "object", "additionalProperties": false, "required": [ "currentLevel", "nextLevel", "badges", "challenges", "referralCampaign" ], "properties": { "currentLevel": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionCustomerLevel" }, { "type": "null" } ] }, "nextLevel": { "oneOf": [ { "$ref": "#/components/schemas/LoyaltyProgressionNextLevel" }, { "type": "null" } ] }, "badges": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyProgressionBadge" }, "maxItems": 50 }, "challenges": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoyaltyProgressionChallenge" }, "maxItems": 50 }, "referralCampaign": { "oneOf": [ { "$ref": "#/components/schemas/CustomerLoyaltyReferralCampaign" }, { "type": "null" } ] } } }, "CustomerLoyaltyReferralIssueResult": { "type": "object", "additionalProperties": false, "required": [ "loyalty" ], "properties": { "loyalty": { "type": "object", "additionalProperties": false, "required": [ "referral", "token", "referralUrl" ], "properties": { "referral": { "$ref": "#/components/schemas/LoyaltyReferral" }, "token": { "type": "string", "minLength": 16, "maxLength": 256 }, "referralUrl": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048 } } } } }, "CustomerLoyaltyReferralIssueEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerLoyaltyReferralIssueResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerLoyaltyReferralClaimResult": { "type": "object", "additionalProperties": false, "required": [ "loyalty" ], "properties": { "loyalty": { "type": "object", "additionalProperties": false, "required": [ "referral" ], "properties": { "referral": { "$ref": "#/components/schemas/LoyaltyReferral" } } } } }, "CustomerLoyaltyReferralClaimEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerLoyaltyReferralClaimResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingChannel": { "type": "string", "enum": [ "facebook", "instagram" ] }, "SocialPublishingConnectionStatus": { "type": "string", "enum": [ "active", "needsReauth", "revoked", "failed" ] }, "SocialPublishingJobStatus": { "type": "string", "enum": [ "scheduled", "processing", "published", "partiallyFailed", "failed", "cancelled" ] }, "SocialPublishingMetaStartInput": { "type": "object", "additionalProperties": false, "required": [], "properties": { "locationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } } }, "SocialPublishingJobCreateInput": { "type": "object", "additionalProperties": false, "required": [ "connectionId", "channels", "caption" ], "properties": { "connectionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "eventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SocialPublishingChannel" }, "minItems": 1, "maxItems": 2 }, "caption": { "type": "string", "minLength": 1, "maxLength": 5000 }, "mediaUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "linkUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" } } }, "SocialPublishingAuthorization": { "type": "object", "additionalProperties": false, "required": [ "authorizationUrl", "expiresAt" ], "properties": { "authorizationUrl": { "type": "string", "format": "uri", "maxLength": 4000 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "SocialPublishingAuthorizationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingAuthorization" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingConnection": { "type": "object", "additionalProperties": false, "required": [ "id", "locationId", "provider", "status", "tokenExpiresAt", "externalAccountId", "accountName", "accountHandle", "accountAvatarUrl", "metaPageId", "instagramAccountId", "channels", "grantedScopes", "lastUsedAt", "lastRefreshedAt", "lastErrorAt", "lastErrorCode", "revokedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "meta" ] }, "status": { "$ref": "#/components/schemas/SocialPublishingConnectionStatus" }, "tokenExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "externalAccountId": { "type": "string", "minLength": 1, "maxLength": 255 }, "accountName": { "type": "string", "minLength": 1, "maxLength": 500 }, "accountHandle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "accountAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "metaPageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "instagramAccountId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SocialPublishingChannel" }, "minItems": 0, "maxItems": 2 }, "grantedScopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 0, "maxItems": 100 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastRefreshedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastErrorAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastErrorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SocialPublishingConnectionResult": { "type": "object", "additionalProperties": false, "required": [ "connection" ], "properties": { "connection": { "$ref": "#/components/schemas/SocialPublishingConnection" } } }, "SocialPublishingConnectionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingConnectionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingWorkspace": { "type": "object", "additionalProperties": false, "required": [ "generatedAt", "providerConfigured", "locations", "events", "connections", "jobs" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "providerConfigured": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "minItems": 0, "maxItems": 200 }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "slug", "locationId", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "slug": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time" } } }, "minItems": 0, "maxItems": 200 }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/SocialPublishingConnection" }, "minItems": 0, "maxItems": 50 }, "jobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "connectionId", "channels", "status", "caption", "scheduledFor", "attempts", "maxAttempts", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "eventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "connectionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SocialPublishingChannel" }, "minItems": 1, "maxItems": 2 }, "status": { "$ref": "#/components/schemas/SocialPublishingJobStatus" }, "caption": { "type": "string", "minLength": 1, "maxLength": 5000 }, "mediaUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "linkUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 1 }, "nextRetryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastErrorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 5000 }, { "type": "null" } ] }, "lastErrorMessage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 5000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "additionalProperties": true }, "event": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "logs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "minItems": 0, "maxItems": 10 } } }, "minItems": 0, "maxItems": 100 } } }, "SocialPublishingWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingJobScheduled": { "type": "object", "additionalProperties": false, "required": [ "job" ], "properties": { "job": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "scheduledFor" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "scheduled" ] }, "scheduledFor": { "type": "string", "format": "date-time" } } } } }, "SocialPublishingJobScheduledEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingJobScheduled" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingRetryResult": { "type": "object", "additionalProperties": false, "required": [ "retried" ], "properties": { "retried": { "type": "boolean", "enum": [ true ] } } }, "SocialPublishingRetryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingRetryResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "SocialPublishingCancelResult": { "type": "object", "additionalProperties": false, "required": [ "cancelled" ], "properties": { "cancelled": { "type": "boolean", "enum": [ true ] } } }, "SocialPublishingCancelEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingCancelResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessStartInput": { "type": "object", "additionalProperties": false, "required": [ "locationId" ], "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "GoogleBusinessSelectInput": { "type": "object", "additionalProperties": false, "required": [ "accountId", "providerLocationName" ], "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 255 }, "providerLocationName": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "GoogleBusinessSyncField": { "type": "string", "enum": [ "description", "phone", "websiteUrl", "openingHours" ] }, "GoogleBusinessSyncInput": { "type": "object", "additionalProperties": false, "required": [ "fields" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleBusinessSyncField" }, "minItems": 1, "maxItems": 4 } } }, "GoogleBusinessAuthorizationEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SocialPublishingAuthorization" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessConnection": { "type": "object", "additionalProperties": false, "required": [ "id", "locationId", "status", "googleAccountId", "googleAccountName", "providerLocationName", "providerLocationTitle", "grantedScopes", "discoveredAccounts", "remoteProfile", "remoteProfileFetchedAt", "lastSyncAt", "lastErrorCode", "lastErrorMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "pending-location", "active", "syncing", "failed", "needs-reauth", "revoked" ] }, "googleAccountId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "googleAccountName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "providerLocationName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "providerLocationTitle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "grantedScopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "minItems": 0, "maxItems": 100 }, "discoveredAccounts": {}, "remoteProfile": {}, "remoteProfileFetchedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastErrorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "lastErrorMessage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 5000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "GoogleBusinessConnectionResult": { "type": "object", "additionalProperties": false, "required": [ "connection" ], "properties": { "connection": { "$ref": "#/components/schemas/GoogleBusinessConnection" } } }, "GoogleBusinessConnectionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GoogleBusinessConnectionResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessWorkspace": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "generatedAt", "providerConfigured", "locations" ], "properties": { "contractVersion": { "type": "string", "enum": [ "vsm-google-business-profile-contract-v1" ] }, "generatedAt": { "type": "string", "format": "date-time" }, "providerConfigured": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "localProfile", "connection", "history" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "localProfile": { "type": "object", "additionalProperties": true }, "connection": { "anyOf": [ { "$ref": "#/components/schemas/GoogleBusinessConnection" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "minItems": 0, "maxItems": 30 } } }, "minItems": 0, "maxItems": 200 } } }, "GoogleBusinessWorkspaceEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GoogleBusinessWorkspace" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessAvailableLocation": { "type": "object", "additionalProperties": false, "required": [ "accountId", "accountName", "providerLocationName", "title", "address", "phone", "websiteUrl", "mapsUrl" ], "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 255 }, "accountName": { "type": "string", "minLength": 1, "maxLength": 500 }, "providerLocationName": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "address": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] }, "mapsUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 4000 }, { "type": "null" } ] } } }, "GoogleBusinessAvailableLocations": { "type": "object", "additionalProperties": false, "required": [ "connectionId", "locations" ], "properties": { "connectionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleBusinessAvailableLocation" }, "minItems": 0, "maxItems": 1000 } } }, "GoogleBusinessAvailableLocationsEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GoogleBusinessAvailableLocations" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessSyncQueued": { "type": "object", "additionalProperties": false, "required": [ "run" ], "properties": { "run": { "type": "object", "additionalProperties": false, "required": [ "id", "status" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "queued" ] } } } } }, "GoogleBusinessSyncQueuedEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GoogleBusinessSyncQueued" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "GoogleBusinessRetryResult": { "type": "object", "additionalProperties": false, "required": [ "retried" ], "properties": { "retried": { "type": "boolean", "enum": [ true ] } } }, "GoogleBusinessRetryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GoogleBusinessRetryResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountDeletionExchangeInput": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } }, "TenantOperatorOfferingDraft": { "type": "object", "additionalProperties": false, "required": [ "name", "durationMinutes", "capacity" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 220 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "capacity": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "eventStartsAt": { "type": "string", "format": "date-time" }, "priceAmount": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "templateKey": { "type": "string", "enum": [ "single_appointment", "consultation", "trial_session", "course", "salon_appointment", "workshop" ] }, "preparationMinutes": { "type": "integer", "minimum": 0, "maximum": 240 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "creationKey": { "type": "string", "format": "uuid" }, "reminderEnabled": { "type": "boolean" }, "reminderLeadMinutes": { "type": "integer", "minimum": 60, "maximum": 10080 }, "pipeline": { "type": "boolean" } } }, "TenantOperatorNavigationPreferences": { "type": "object", "additionalProperties": false, "properties": { "favorites": { "type": "array", "items": { "type": "string", "enum": [ "overview", "onboarding", "launch", "billing", "addOns", "calendar", "resources", "customers", "communication", "loyalty", "memberships", "seatmaps", "events", "tickets", "analytics", "embeds", "websiteSync", "publicProfile", "googleBusiness", "team", "security", "help", "admin", "leads", "tasks", "participants", "landingPages", "leadSequences", "developers" ] }, "maxItems": 8, "minItems": 0, "uniqueItems": true }, "recent": { "type": "array", "items": { "type": "string", "enum": [ "overview", "onboarding", "launch", "billing", "addOns", "calendar", "resources", "customers", "communication", "loyalty", "memberships", "seatmaps", "events", "tickets", "analytics", "embeds", "websiteSync", "publicProfile", "googleBusiness", "team", "security", "help", "admin", "leads", "tasks", "participants", "landingPages", "leadSequences", "developers" ] }, "maxItems": 8, "minItems": 0, "uniqueItems": true } } }, "CommercialTermStatus": { "type": "string", "enum": [ "approved", "external_blocked" ] }, "CommercialTermsApproval": { "type": "object", "additionalProperties": false, "required": [ "status", "approvedAt" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "approvedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CommercialTermsVat": { "type": "object", "additionalProperties": false, "required": [ "status", "pricesIncludeVat", "rateBasisPoints", "note" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "pricesIncludeVat": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rateBasisPoints": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } } }, "CommercialTermsVolume": { "type": "object", "additionalProperties": false, "required": [ "unit", "quantity" ], "properties": { "unit": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "quantity": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } } }, "CommercialTermsIncludedUsage": { "type": "object", "additionalProperties": false, "required": [ "status", "users", "locations", "volume" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "users": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "locations": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "volume": { "$ref": "#/components/schemas/CommercialTermsVolume" } } }, "CommercialTermsFee": { "type": "object", "additionalProperties": false, "required": [ "status", "percentageBasisPoints", "fixedAmountMinor", "currency", "note" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "percentageBasisPoints": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "fixedAmountMinor": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } } }, "CommercialTermsTrial": { "type": "object", "additionalProperties": false, "required": [ "status", "days", "note" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "days": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } } }, "CommercialTermsCancellation": { "type": "object", "additionalProperties": false, "required": [ "status", "noticePeriodDays", "effectiveAt", "note" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "noticePeriodDays": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "effectiveAt": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } } }, "CommercialTermsPlanChange": { "type": "object", "additionalProperties": false, "required": [ "status", "policy", "note" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "policy": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "note": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } } }, "CommercialTermsAllInLineItem": { "type": "object", "additionalProperties": false, "required": [ "label", "amountMinor" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 320 }, "amountMinor": { "type": "integer", "minimum": 0 } } }, "CommercialTermsAllInExample": { "type": "object", "additionalProperties": false, "required": [ "status", "currency", "scenario", "lineItems", "totalMinor" ], "properties": { "status": { "$ref": "#/components/schemas/CommercialTermStatus" }, "currency": { "oneOf": [ { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "scenario": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "lineItems": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CommercialTermsAllInLineItem" }, "maxItems": 100, "minItems": 1 }, { "type": "null" } ] }, "totalMinor": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } } }, "CommercialTermsContract": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "catalogVersion", "approval", "vat", "includedUsage", "fees", "trial", "cancellation", "planChange", "allInExample" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-commercial-terms-v1" }, "catalogVersion": { "type": "string", "minLength": 1, "maxLength": 160 }, "approval": { "$ref": "#/components/schemas/CommercialTermsApproval" }, "vat": { "$ref": "#/components/schemas/CommercialTermsVat" }, "includedUsage": { "type": "object", "additionalProperties": false, "required": [ "base", "growth", "platform" ], "properties": { "base": { "$ref": "#/components/schemas/CommercialTermsIncludedUsage" }, "growth": { "$ref": "#/components/schemas/CommercialTermsIncludedUsage" }, "platform": { "$ref": "#/components/schemas/CommercialTermsIncludedUsage" } } }, "fees": { "type": "object", "additionalProperties": false, "required": [ "platform", "transaction", "paymentProcessing" ], "properties": { "platform": { "$ref": "#/components/schemas/CommercialTermsFee" }, "transaction": { "$ref": "#/components/schemas/CommercialTermsFee" }, "paymentProcessing": { "$ref": "#/components/schemas/CommercialTermsFee" } } }, "trial": { "$ref": "#/components/schemas/CommercialTermsTrial" }, "cancellation": { "$ref": "#/components/schemas/CommercialTermsCancellation" }, "planChange": { "$ref": "#/components/schemas/CommercialTermsPlanChange" }, "allInExample": { "$ref": "#/components/schemas/CommercialTermsAllInExample" } } }, "BillingVerifiedPrice": { "type": "object", "additionalProperties": false, "required": [ "status", "amountMinor", "currency", "recurringInterval", "recurringIntervalCount", "verifiedAt", "unavailableReason" ], "properties": { "status": { "type": "string", "const": "verified" }, "amountMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3 }, "recurringInterval": { "type": "string", "enum": [ "month", "year" ] }, "recurringIntervalCount": { "type": "integer", "minimum": 1 }, "verifiedAt": { "type": "string", "format": "date-time" }, "unavailableReason": { "type": "null" } } }, "BillingUnavailablePrice": { "type": "object", "additionalProperties": false, "required": [ "status", "amountMinor", "currency", "recurringInterval", "recurringIntervalCount", "verifiedAt", "unavailableReason" ], "properties": { "status": { "type": "string", "const": "unavailable" }, "amountMinor": { "type": "null" }, "currency": { "type": "null" }, "recurringInterval": { "type": "null" }, "recurringIntervalCount": { "type": "null" }, "verifiedAt": { "type": "null" }, "unavailableReason": { "type": "string", "enum": [ "not_configured", "checkout_not_supported" ] } } }, "PublicTicketSeatHoldGroupTargetInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "seatUnitId" ], "properties": { "seatUnitId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "seatBlockId" ], "properties": { "seatBlockId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 } } } ] }, "PublicTicketSeatHoldGroupInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "ticketTypeId", "targets" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldGroupTargetInput" }, "maxItems": 20, "minItems": 1 } } }, "PublicTicketSeatHoldBestAvailableInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "ticketTypeId", "quantity" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "accessibility": { "type": "object", "additionalProperties": false, "properties": { "wheelchairAccessible": { "type": "boolean" }, "companionSeat": { "type": "boolean" } } }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "PublicTicketSeatHoldManualGroupRanking": { "type": "object", "additionalProperties": false, "required": [ "strategy", "atomic", "targetCount", "quantity", "ticketTypeId", "priceAmount" ], "properties": { "strategy": { "type": "string", "const": "vsm-manual-seat-group-v1" }, "atomic": { "type": "boolean", "const": true }, "targetCount": { "type": "integer", "minimum": 1, "maximum": 20 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 } } }, "PublicTicketSeatHoldBestAvailableRanking": { "type": "object", "additionalProperties": false, "required": [ "strategy", "rowKey", "contiguous", "orphanSeatCount", "orphanSeatsAvoided", "distanceScore", "restrictedViewCount", "accessibilityMatched" ], "properties": { "strategy": { "type": "string", "const": "vsm-best-available-v1" }, "rowKey": { "type": "string", "minLength": 1, "maxLength": 500 }, "contiguous": { "type": "boolean", "const": true }, "orphanSeatCount": { "type": "integer", "minimum": 0, "maximum": 2 }, "orphanSeatsAvoided": { "type": "boolean" }, "distanceScore": { "type": "number", "minimum": 0 }, "restrictedViewCount": { "type": "integer", "minimum": 0, "maximum": 20 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "priceAmount": { "type": "integer", "minimum": 0 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "rowLabel": { "type": "string", "minLength": 1, "maxLength": 220 }, "accessibilityMatched": { "type": "object", "additionalProperties": false, "required": [ "wheelchairAccessible", "companionSeat" ], "properties": { "wheelchairAccessible": { "type": "boolean" }, "companionSeat": { "type": "boolean" } } } } }, "PublicTicketSeatHoldGroupResult": { "type": "object", "additionalProperties": false, "required": [ "holds", "targets", "expired", "ranking" ], "properties": { "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "maxItems": 20, "minItems": 1 }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatTarget" }, "maxItems": 20, "minItems": 1 }, "expired": { "type": "integer", "minimum": 0 }, "ranking": { "$ref": "#/components/schemas/PublicTicketSeatHoldManualGroupRanking" } } }, "PublicTicketSeatHoldGroupEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldGroupResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatHoldBestAvailableResult": { "type": "object", "additionalProperties": false, "required": [ "holds", "targets", "expired", "ranking" ], "properties": { "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "maxItems": 20, "minItems": 1 }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatTarget" }, "maxItems": 20, "minItems": 1 }, "expired": { "type": "integer", "minimum": 0 }, "ranking": { "$ref": "#/components/schemas/PublicTicketSeatHoldBestAvailableRanking" } } }, "PublicTicketSeatHoldBestAvailableEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatHoldBestAvailableResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatWaitlistJoinInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "eventInstanceId", "ticketTypeId", "guestName", "guestEmail", "quantity" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locationSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "accessibility": { "type": "object", "additionalProperties": false, "properties": { "wheelchairAccessible": { "type": "boolean" }, "companionSeat": { "type": "boolean" } } }, "secretAccess": { "$ref": "#/components/schemas/PublicEventSecretAccessInput" } } }, "PublicTicketSeatWaitlistManageInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "entryId", "manageToken" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "entryId": { "type": "string", "minLength": 1, "maxLength": 160 }, "manageToken": { "type": "string", "pattern": "^tswm_[A-Za-z0-9_-]{40,80}$" } } }, "PublicTicketSeatWaitlistAcceptInput": { "type": "object", "additionalProperties": false, "required": [ "tenantSlug", "offeringId", "entryId", "offerToken" ], "properties": { "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "entryId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offerToken": { "type": "string", "pattern": "^tswo_[A-Za-z0-9_-]{40,80}$" } } }, "PublicTicketSeatWaitlistOffer": { "type": "object", "additionalProperties": false, "required": [ "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": "string", "format": "date-time" } } }, "PublicTicketSeatWaitlistEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "offeringId", "eventInstanceId", "ticketTypeId", "quantity", "position", "ahead", "status", "accessibility" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "position": { "type": "integer", "minimum": 1 }, "ahead": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "waiting", "offered", "cancelled", "expired", "removed" ] }, "accessibility": { "type": "object", "additionalProperties": false, "required": [ "wheelchairAccessible", "companionSeat" ], "properties": { "wheelchairAccessible": { "type": "boolean" }, "companionSeat": { "type": "boolean" } } }, "offer": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistOffer" } } }, "PublicTicketSeatWaitlistJoinResult": { "type": "object", "additionalProperties": false, "required": [ "alreadyJoined", "entry" ], "properties": { "alreadyJoined": { "type": "boolean" }, "manageToken": { "type": "string", "pattern": "^tswm_[A-Za-z0-9_-]{40,80}$" }, "entry": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistEntry" } } }, "PublicTicketSeatWaitlistJoinEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistJoinResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatWaitlistEntryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistEntry" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicTicketSeatWaitlistPrice": { "type": "object", "additionalProperties": false, "required": [ "ticketTypeId", "unitAmount", "currency", "quantity" ], "properties": { "ticketTypeId": { "type": "string", "minLength": 1, "maxLength": 160 }, "unitAmount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 } } }, "PublicTicketSeatWaitlistAcceptResult": { "type": "object", "additionalProperties": false, "required": [ "entry", "price", "holds" ], "properties": { "entry": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistEntry" }, "price": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistPrice" }, "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTicketSeatHoldSnapshot" }, "maxItems": 20, "minItems": 1 } } }, "PublicTicketSeatWaitlistAcceptEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTicketSeatWaitlistAcceptResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingRescheduleInput": { "type": "object", "additionalProperties": false, "required": [ "startsAt", "endsAt" ], "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 } } }, "WorkspaceAggregateOperatorInboxPage": { "type": "object", "additionalProperties": false, "required": [ "limit", "returned", "hasMore" ], "properties": { "limit": { "type": "integer", "minimum": 24, "maximum": 24 }, "returned": { "type": "integer", "minimum": 0, "maximum": 24 }, "hasMore": { "type": "boolean" } } }, "AuthRegistrationRequestData": { "type": "object", "additionalProperties": false, "required": [ "accepted", "verificationRequired", "email" ], "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "verificationRequired": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "developmentToken": { "type": "string" } } }, "AuthRegistrationRequestEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuthRegistrationRequestData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CustomerAccountPushDiagnosticInput": { "type": "object", "additionalProperties": false, "required": [ "version", "stage", "code", "permission", "standalone", "serviceWorkerState" ], "properties": { "version": { "type": "string", "const": "vsm-push-diagnostic-v1" }, "stage": { "type": "string", "enum": [ "availability", "permission", "subscribe", "api" ] }, "code": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Z0-9_]+$" }, "permission": { "type": "string", "enum": [ "default", "denied", "granted" ] }, "standalone": { "type": "boolean" }, "serviceWorkerState": { "type": "string", "enum": [ "none", "installing", "waiting", "active" ] } } }, "CustomerAccountPushDiagnosticResult": { "type": "object", "additionalProperties": false, "required": [ "accepted" ], "properties": { "accepted": { "type": "boolean", "const": true } } }, "CustomerAccountPushDiagnosticEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAccountPushDiagnosticResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingReminderPlanView": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "bookingId", "policyVersion", "leadMinutes", "preparationText", "locale", "timezone", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 191 }, "policyVersion": { "type": "integer", "minimum": 1 }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "pending", "queued", "skipped", "cancelled" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 120 }, "messageId": { "type": "string", "minLength": 1, "maxLength": 191 }, "deliveryStatus": { "type": "string", "enum": [ "draft", "queued", "processing", "sent", "failed", "cancelled" ] }, "scheduledAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BookingReminderPlanResult": { "type": "object", "additionalProperties": false, "required": [ "plan" ], "properties": { "plan": { "anyOf": [ { "$ref": "#/components/schemas/BookingReminderPlanView" }, { "type": "null" } ] } } }, "BookingReminderPlanEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingReminderPlanResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingReminderPreviewInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "locationId", "serviceName", "reminderDefaults" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceName": { "type": "string", "minLength": 2, "maxLength": 160 }, "reminderDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "leadMinutes", "preparationText" ], "properties": { "enabled": { "type": "boolean" }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "preparationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } } } }, "BookingReminderPreview": { "type": "object", "additionalProperties": false, "required": [ "subject", "bodyHtml", "bodyText", "layoutVersion", "locale", "timezone", "exampleStartsAt", "exampleScheduledAt", "exampleData" ], "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 100000 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "layoutVersion": { "type": "string", "const": "vsm-email-layout-v1" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "exampleStartsAt": { "type": "string", "format": "date-time" }, "exampleScheduledAt": { "type": "string", "format": "date-time" }, "exampleData": { "type": "boolean", "const": true } } }, "BookingReminderPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingReminderPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingRecoveryPlanView": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "bookingId", "sourceRevision", "policyVersion", "delayMinutes", "validForDays", "invitationText", "locale", "timezone", "noShowAt", "dueAt", "expiresAt", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceRevision": { "type": "integer", "minimum": 1 }, "policyVersion": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "validForDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "invitationText": { "type": "string", "minLength": 0, "maxLength": 4000 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "noShowAt": { "type": "string", "format": "date-time" }, "dueAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "queued", "stopped", "skipped", "expired", "recovered" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 120 }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "messageId", "status", "scheduledAt", "sentAt", "failedAt", "nextAttemptAt", "updatedAt", "repair" ], "properties": { "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "queued", "processing", "sent", "failed", "cancelled" ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "repair": { "type": "string", "enum": [ "retryAvailable", "outcomeReviewRequired", "notAvailable" ] } } }, "rebooking": { "type": "object", "additionalProperties": false, "required": [ "bookingId", "status", "requestedAt", "firstConfirmedAt", "attendedAt" ], "properties": { "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "firstConfirmedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attendedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BookingRecoveryPlanResult": { "type": "object", "additionalProperties": false, "required": [ "plan" ], "properties": { "plan": { "anyOf": [ { "$ref": "#/components/schemas/BookingRecoveryPlanView" }, { "type": "null" } ] } } }, "BookingRecoveryPlanEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingRecoveryPlanResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicBookingRecoveryContext": { "type": "object", "additionalProperties": false, "required": [ "planId", "tenantSlug", "locale", "expiresAt", "location", "calendar", "service", "guest" ], "properties": { "planId": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantSlug": { "type": "string", "minLength": 2, "maxLength": 160, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "location": { "$ref": "#/components/schemas/Location" }, "calendar": { "$ref": "#/components/schemas/Calendar" }, "service": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "durationMinutes" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 } } }, "guest": { "type": "object", "additionalProperties": false, "required": [ "name", "email", "phone" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "minLength": 0, "maxLength": 64 } } }, "rebooking": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "startsAt", "endsAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } } } }, "PublicBookingRecoveryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicBookingRecoveryContext" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicBookingRecoveryCreateInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "slotId", "guestName", "guestEmail", "partySize", "startsAt", "endsAt" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "guestName": { "type": "string", "minLength": 2, "maxLength": 160 }, "guestEmail": { "type": "string", "format": "email", "maxLength": 320 }, "guestPhone": { "type": "string", "minLength": 3, "maxLength": 64 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "notes": { "type": "string", "minLength": 0, "maxLength": 5000 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } }, "AdminWorkflowDeliveryStatus": { "type": "string", "enum": [ "PENDING", "PROCESSING", "FAILED", "DEAD_LETTER", "PROCESSED" ] }, "AdminWorkflowDeliveryQuery": { "type": "object", "additionalProperties": false, "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "$ref": "#/components/schemas/AdminWorkflowDeliveryStatus" }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "AdminWorkflowDeliveryRetryInput": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "reason", "expectedUpdatedAt" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 }, "expectedUpdatedAt": { "type": "string", "format": "date-time" } } }, "AdminWorkflowDeliverySummary": { "type": "object", "additionalProperties": false, "required": [ "id", "eventId", "consumerId", "status", "attemptCount", "availableAt", "leaseExpiresAt", "leaseExpired", "completedAt", "failureCode", "updatedAt", "retryable", "eventType", "resourceId", "resourceRevision", "occurredAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "consumerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "$ref": "#/components/schemas/AdminWorkflowDeliveryStatus" }, "attemptCount": { "type": "integer", "minimum": 0 }, "availableAt": { "type": "string", "format": "date-time" }, "leaseExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "leaseExpired": { "type": "boolean" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "enum": [ "PROCESSING_FAILED", "INVALID_EVENT_CONTRACT", "LEASE_EXHAUSTED", "UNKNOWN_FAILURE" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "retryable": { "type": "boolean" }, "eventType": { "type": "string", "minLength": 1, "maxLength": 64 }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 200 }, "resourceRevision": { "type": "integer", "minimum": 0 }, "occurredAt": { "type": "string", "format": "date-time" } } }, "AdminWorkflowDeliveryPageData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "generatedAt", "tenantId", "offset", "limit", "total", "items", "canRetry" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-workflow-delivery-ops-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "total": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AdminWorkflowDeliverySummary" } }, "canRetry": { "type": "boolean" } } }, "AdminWorkflowDeliveryPageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkflowDeliveryPageData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminWorkflowDeliveryRetryData": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "deliveryId", "tenantId", "status", "updatedAt", "auditEventId" ], "properties": { "schemaVersion": { "type": "string", "const": "vsm-workflow-delivery-retry-v1" }, "deliveryId": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "const": "PENDING" }, "updatedAt": { "type": "string", "format": "date-time" }, "auditEventId": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "AdminWorkflowDeliveryRetryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminWorkflowDeliveryRetryData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationQuietHours": { "type": "object", "additionalProperties": false, "required": [ "enabled", "startTime", "endTime", "timezone" ], "properties": { "enabled": { "type": "boolean" }, "startTime": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "endTime": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "CommunicationPolicy": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "version", "revision", "quietHours", "updatedAt" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "version": { "type": "string", "const": "vsm-communication-quiet-hours-v1" }, "revision": { "type": "integer", "minimum": 0 }, "quietHours": { "$ref": "#/components/schemas/CommunicationQuietHours" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "CommunicationPolicyInput": { "type": "object", "additionalProperties": false, "required": [ "expectedTenantId", "expectedRevision", "quietHours" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 2147483646 }, "quietHours": { "$ref": "#/components/schemas/CommunicationQuietHours" } } }, "CommunicationPolicyEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CommunicationPolicy" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationUsage": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "unit", "version", "periodStart", "periodEnd", "budget", "warnings", "reserved", "consumed", "unknown", "price", "recent" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "unit": { "type": "string", "const": "email.nontransactional.accepted" }, "version": { "type": "string", "const": "vsm-communication-usage-v1" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "budget": { "type": "object", "additionalProperties": false, "required": [ "revision", "monthlyLimit", "warningPercent", "smsMonthlyLimit", "whatsappMonthlyLimit" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "monthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "warningPercent": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "smsMonthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "whatsappMonthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] } } }, "warnings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "thresholdPercent", "reachedAt" ], "properties": { "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "reachedAt": { "type": "string", "format": "date-time" } } } }, "reserved": { "type": "integer", "minimum": 0 }, "consumed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "price": { "type": "object", "additionalProperties": false, "required": [ "status", "version", "currency", "unitPriceMinor" ], "properties": { "status": { "type": "string", "const": "unpriced" }, "version": { "type": "null" }, "currency": { "type": "null" }, "unitPriceMinor": { "type": "null" } } }, "recent": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "revision", "periodStart", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "RESERVED", "CONSUMED", "RELEASED", "UNKNOWN" ] }, "revision": { "type": "integer", "minimum": 1 }, "periodStart": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "CommunicationBudgetInput": { "type": "object", "additionalProperties": false, "required": [ "expectedTenantId", "expectedRevision", "monthlyLimit" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 2147483646 }, "monthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "warningPercent": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "smsMonthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] }, "whatsappMonthlyLimit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000 }, { "type": "null" } ] } } }, "CommunicationUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CommunicationUsage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationUsageReservationExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "emailMessageId", "unit", "unitVersion", "periodStart", "status", "revision", "claimStartedAt", "provider", "receiptDigest", "priceVersion", "currency", "unitPriceMinor", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMessageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "unit": { "type": "string", "minLength": 1, "maxLength": 64 }, "unitVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "periodStart": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "RESERVED", "CONSUMED", "RELEASED", "UNKNOWN" ] }, "revision": { "type": "integer", "minimum": 1 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "provider": { "type": "string", "minLength": 1, "maxLength": 64 }, "receiptDigest": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "priceVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "unitPriceMinor": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CommunicationUsageEntryExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "reservationId", "sequence", "unit", "unitVersion", "periodStart", "kind", "reservedDelta", "consumedDelta", "priceVersion", "currency", "unitPriceMinor", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sequence": { "type": "integer", "minimum": 1 }, "unit": { "type": "string", "minLength": 1, "maxLength": 64 }, "unitVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "periodStart": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "RESERVE", "CONSUME", "RELEASE", "UNKNOWN" ] }, "reservedDelta": { "type": "integer", "minimum": -1, "maximum": 1 }, "consumedDelta": { "type": "integer", "minimum": 0, "maximum": 1 }, "priceVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "unitPriceMinor": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CommunicationUsageDetail": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "reservationId", "revision", "status", "claimStartedAt", "provider", "emailMessageId", "mailStatus", "canResolve", "blockedReason", "evidence" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "RESERVED", "UNKNOWN", "CONSUMED", "RELEASED" ] }, "claimStartedAt": { "type": "string", "format": "date-time" }, "provider": { "type": "string", "minLength": 2, "maxLength": 64 }, "emailMessageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "mailStatus": { "anyOf": [ { "type": "string", "enum": [ "DRAFT", "QUEUED", "PROCESSING", "SENT", "FAILED", "CANCELLED" ] }, { "type": "null" } ] }, "canResolve": { "type": "boolean" }, "blockedReason": { "anyOf": [ { "type": "string", "enum": [ "notUnknown", "noEvidence", "conflictingEvidence", "mailUnavailable", "mailChanged", "positiveTransportFact" ] }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "outcome", "receivedAt", "source" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted" ] }, "receivedAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "const": "signedRelay" } } }, "maxItems": 50 } } }, "CommunicationUsageDetailEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CommunicationUsageDetail" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationUsageReconcileInput": { "type": "object", "additionalProperties": false, "required": [ "expectedTenantId", "expectedRevision", "evidenceId", "commandKey", "reason" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "commandKey": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } } }, "CommunicationUsageReconcileResult": { "type": "object", "additionalProperties": false, "required": [ "reservationId", "evidenceId", "status", "revision", "replayed" ], "properties": { "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "CONSUMED", "RELEASED" ] }, "revision": { "type": "integer", "minimum": 2 }, "replayed": { "type": "boolean" } } }, "CommunicationUsageReconcileEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CommunicationUsageReconcileResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationUsageEvidenceExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "reservationId", "provider", "providerEventId", "claimStartedAt", "outcome", "version", "payloadDigest", "receiptDigest", "receivedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "provider": { "type": "string", "minLength": 2, "maxLength": 64 }, "providerEventId": { "type": "string", "minLength": 1, "maxLength": 255 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted" ] }, "version": { "type": "string", "const": "vsm-mail-transport-receipt-v1" }, "payloadDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "receiptDigest": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time" } } }, "CommunicationUsageResolutionExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "reservationId", "evidenceId", "expectedRevision", "commandKey", "commandDigest", "status", "resultRevision", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedRevision": { "type": "integer", "minimum": 1 }, "commandKey": { "type": "string", "minLength": 8, "maxLength": 64 }, "commandDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string", "enum": [ "CONSUMED", "RELEASED" ] }, "resultRevision": { "type": "integer", "minimum": 2 }, "createdAt": { "type": "string", "format": "date-time" } } }, "SignedTransportAcceptedInput": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "tenantId", "messageId", "providerMessageId", "transportReceipt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "const": "transport.accepted" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "providerMessageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "transportReceipt": { "type": "object", "additionalProperties": false, "required": [ "version", "reservationId", "claimStartedAt", "outcome" ], "properties": { "version": { "type": "string", "const": "vsm-mail-transport-receipt-v1" }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "outcome": { "type": "string", "const": "accepted" } } } } }, "SignedTransportNotAcceptedInput": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "tenantId", "messageId", "transportReceipt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "const": "transport.not_accepted" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "transportReceipt": { "type": "object", "additionalProperties": false, "required": [ "version", "reservationId", "claimStartedAt", "outcome" ], "properties": { "version": { "type": "string", "const": "vsm-mail-transport-receipt-v1" }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "outcome": { "type": "string", "const": "notAccepted" } } } } }, "LegacyEmailProviderEventInput": { "type": "object", "additionalProperties": true, "required": [ "id", "type" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 80, "not": { "pattern": "^transport\\." } }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "providerMessageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "recipientEmail": { "type": "string", "format": "email", "maxLength": 320 }, "reason": { "type": "string", "minLength": 0, "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": true } }, "not": { "required": [ "transportReceipt" ] } }, "CommunicationUsagePendingPage": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "items", "nextCursor" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "revision", "claimStartedAt", "provider", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "integer", "minimum": 1 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "provider": { "type": "string", "minLength": 2, "maxLength": 64 }, "createdAt": { "type": "string", "format": "date-time" } } }, "maxItems": 20 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } } }, "CommunicationUsagePendingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CommunicationUsagePendingPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "CommunicationRecipientPreview": { "type": "object", "additionalProperties": false, "required": [ "policyVersion", "tenantId", "checkedAt", "purpose", "status", "eligibleRecipients", "blockedRecipients", "reasonCounts", "finalCheckRequired" ], "properties": { "policyVersion": { "type": "string", "const": "vsm-communication-send-policy-v1" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "checkedAt": { "type": "string", "format": "date-time" }, "purpose": { "type": "string", "const": "marketing" }, "status": { "type": "string", "enum": [ "evaluated", "unavailable" ] }, "eligibleRecipients": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 5000 }, { "type": "null" } ] }, "blockedRecipients": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 5000 }, { "type": "null" } ] }, "finalCheckRequired": { "type": "boolean", "const": true }, "reasonCounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "count" ], "properties": { "code": { "type": "string", "enum": [ "TENANT_REQUIRED", "CONTACT_CHANGED", "CONTACT_UNAVAILABLE", "CONSENT_REQUIRED", "CONSENT_DENIED", "CHANNEL_OPTED_OUT", "CONTACT_SUPPRESSED" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 5000 } } }, "maxItems": 7 } } }, "EmailBroadcastPlanView": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "commandKey", "state", "policyVersion", "origin", "originEventId", "originEventStartsAt", "originBookingId", "originBookingStartsAt", "cancelledPrevious", "supersededAt", "audience", "recipientCount", "eligibleRecipients", "blockedRecipients", "checkedAt", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "commandKey": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "accepted", "erased", "expired" ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "origin": { "type": "string", "enum": [ "communication", "eventReminder", "manualBookingReminder" ] }, "originEventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "originEventStartsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "originBookingId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "originBookingStartsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledPrevious": { "type": "integer", "minimum": 0 }, "supersededAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "audience": { "type": "string", "enum": [ "direct", "tenantMembers", "bookingGuests", "eventAttendees", "ticketBuyers" ] }, "recipientCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "eligibleRecipients": { "type": "integer", "minimum": 0, "maximum": 5000 }, "blockedRecipients": { "type": "integer", "minimum": 0, "maximum": 5000 }, "checkedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WaitlistOfferCommandExport": { "type": "object", "additionalProperties": false, "required": [ "id", "commandKey", "state", "entryId", "messageId", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "commandKey": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "ACCEPTED", "EXPIRED", "ERASED" ] }, "entryId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "messageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "BookingRecoveryPreviewInput": { "type": "object", "additionalProperties": false, "required": [ "calendarId", "locationId", "serviceName", "recoveryDefaults" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "serviceName": { "type": "string", "minLength": 2, "maxLength": 160 }, "recoveryDefaults": { "type": "object", "additionalProperties": false, "required": [ "enabled", "delayMinutes", "validForDays", "invitationText" ], "properties": { "enabled": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "validForDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "invitationText": { "type": "string", "minLength": 0, "maxLength": 4000 } } } } }, "BookingRecoveryPreview": { "type": "object", "additionalProperties": false, "required": [ "subject", "bodyHtml", "bodyText", "layoutVersion", "locale", "timezone", "exampleData" ], "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 220 }, "bodyHtml": { "type": "string", "minLength": 1, "maxLength": 100000 }, "bodyText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "layoutVersion": { "type": "string", "const": "vsm-email-layout-v1" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "exampleData": { "type": "boolean", "const": true } } }, "BookingRecoveryPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingRecoveryPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingRecoveryRetryInput": { "type": "object", "additionalProperties": false, "required": [ "messageId", "expectedUpdatedAt" ], "properties": { "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expectedUpdatedAt": { "type": "string", "format": "date-time" } } }, "BookingRecoveryRetryResult": { "type": "object", "additionalProperties": false, "required": [ "plan", "replayed" ], "properties": { "plan": { "anyOf": [ { "$ref": "#/components/schemas/BookingRecoveryPlanView" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } } }, "BookingRecoveryRetryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookingRecoveryRetryResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "BookingRecoveryRetryCommandExport": { "type": "object", "additionalProperties": false, "required": [ "id", "commandKey", "state", "planId", "messageId", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "commandKey": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "ACCEPTED", "EXPIRED" ] }, "planId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "messageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AcquisitionContact": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "ways": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "sourceContactId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "kind", "value", "sourceContactId" ] }, "maxItems": 20 }, "customerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "verifiedIdentity": { "const": false, "type": "boolean" }, "customerLink": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "confirmedAt": { "type": "string", "format": "date-time" }, "method": { "type": "string", "const": "inPersonConfirmation" }, "accountVerified": { "type": "boolean" } }, "required": [ "confirmedAt", "method", "accountVerified" ] }, { "type": "null" } ] }, "marketingConsent": { "const": "unknown", "type": "string" }, "lastActivityAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "displayName", "email", "phone", "ways", "customerId", "verifiedIdentity", "customerLink", "marketingConsent", "lastActivityAt", "updatedAt" ] }, "AcquisitionOffer": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] } }, "required": [ "id", "name", "locationId" ] }, "AcquisitionContactInput": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "type": "string", "minLength": 1, "maxLength": 320, "format": "email" }, "phone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Plus-prefixed international phone; storage normalization is not identity verification." } }, "required": [ "displayName" ] }, "AcquisitionLead": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "configurationVersion": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "assignment": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionAssignment" }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 80 }, "lossReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "contact": { "$ref": "#/components/schemas/AcquisitionContact" }, "service": { "$ref": "#/components/schemas/AcquisitionOffer" } }, "required": [ "id", "revision", "stage", "configurationVersion", "assignment", "source", "lossReason", "createdAt", "updatedAt", "contact", "service" ] }, "AcquisitionLeadDetail": { "type": "object", "additionalProperties": false, "properties": { "booking": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionBookingView" }, { "type": "null" } ] }, "membership": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionMembershipView" }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "configurationVersion": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "assignment": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionAssignment" }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 80 }, "lossReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "contact": { "$ref": "#/components/schemas/AcquisitionContact" }, "service": { "$ref": "#/components/schemas/AcquisitionOffer" }, "intake": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionIntake" }, { "type": "null" } ] }, "historyHasMore": { "type": "boolean" }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "action": { "type": "string", "minLength": 1, "maxLength": 40 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "configurationVersion": { "type": "integer", "minimum": 1 }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "bookingId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "bookingRevision": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "subscriptionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "assignedMemberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "previousAssignedMemberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "stageLabels": { "type": "object", "additionalProperties": false, "properties": { "de": { "type": "string", "minLength": 1, "maxLength": 64 }, "en": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "de", "en" ] } }, "required": [ "id", "action", "stage", "configurationVersion", "reason", "occurredAt", "bookingId", "bookingRevision", "subscriptionId", "invoiceId", "assignedMemberId", "previousAssignedMemberId", "stageLabels" ] }, "maxItems": 100 } }, "required": [ "booking", "membership", "id", "revision", "stage", "configurationVersion", "assignment", "source", "lossReason", "createdAt", "updatedAt", "contact", "service", "intake", "historyHasMore", "history" ] }, "AcquisitionCaptureInput": { "type": "object", "additionalProperties": false, "properties": { "contact": { "$ref": "#/components/schemas/AcquisitionContactInput" }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "source": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "serviceId", "source" ], "oneOf": [ { "required": [ "contact" ], "not": { "required": [ "contactId" ] } }, { "required": [ "contactId" ], "not": { "required": [ "contact" ] } } ] }, "AcquisitionMoveInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "contacted", "offered" ] } }, "required": [ "expectedRevision", "stage" ] }, "AcquisitionCloseInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "expectedRevision", "reason" ] }, "AcquisitionReopenInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "expectedRevision" ] }, "AcquisitionErasureInput": { "type": "object", "additionalProperties": false, "properties": { "expectedUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedUpdatedAt" ] }, "AcquisitionCommandResult": { "type": "object", "additionalProperties": false, "properties": { "lead": { "$ref": "#/components/schemas/AcquisitionLeadDetail" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "lead", "replayed", "acceptedRevision" ] }, "AcquisitionErasureResult": { "type": "object", "additionalProperties": false, "properties": { "erased": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" } }, "required": [ "erased", "replayed" ] }, "AcquisitionLeadPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionLead" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionOfferOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionOffer" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionContactExport": { "type": "object", "additionalProperties": false, "properties": { "bookingCaptures": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionBookingCaptureRecord" }, "maxItems": 100 }, "contractVersion": { "type": "string", "const": "vsm-acquisition-lead-v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "contact": { "$ref": "#/components/schemas/AcquisitionContactRecord" }, "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionOpportunityRecord" }, "maxItems": 100 }, "phaseConfigurations": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" }, "maxItems": 1100 } }, "required": [ "bookingCaptures", "contractVersion", "generatedAt", "contact", "opportunities", "phaseConfigurations" ] }, "AcquisitionPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionLeadPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionOfferOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionDetailEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "lead": { "$ref": "#/components/schemas/AcquisitionLeadDetail" } }, "required": [ "lead" ] }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionExportEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionContactExport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionErasureEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionErasureResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionContactRecord": { "type": "object", "additionalProperties": false, "properties": { "ways": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "emailOrPhone": { "type": "string", "minLength": 1, "maxLength": 320 }, "sourceContactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "contactId", "kind", "emailOrPhone", "sourceContactId", "createdAt" ] }, "maxItems": 20 }, "mergedSources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "sourceContactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "mergedAt": { "type": "string", "format": "date-time" } }, "required": [ "sourceContactId", "mergedAt" ] }, "maxItems": 100 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailNormalized": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 320 }, { "type": "null" } ] }, "phoneNormalized": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "customerLinkedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "customerLinkMethod": { "anyOf": [ { "type": "string", "const": "inPersonConfirmation" }, { "type": "null" } ] }, "customerLinkUserId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "lastActivityAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "ways", "mergedSources", "id", "tenantId", "displayName", "emailNormalized", "phoneNormalized", "customerId", "customerLinkedAt", "customerLinkMethod", "customerLinkUserId", "lastActivityAt", "createdAt", "updatedAt" ] }, "AcquisitionHistoryRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "action": { "type": "string", "minLength": 1, "maxLength": 40 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "configurationVersion": { "type": "integer", "minimum": 1 }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "bookingId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "bookingRevision": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "subscriptionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "invoiceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "assignedMemberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "previousAssignedMemberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1 }, "actorUserId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "id", "action", "stage", "configurationVersion", "reason", "occurredAt", "bookingId", "bookingRevision", "subscriptionId", "invoiceId", "assignedMemberId", "previousAssignedMemberId", "tenantId", "leadId", "revision", "actorUserId" ] }, "AcquisitionOpportunityRecord": { "type": "object", "additionalProperties": false, "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTaskRecord" }, "maxItems": 100 }, "assignment": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionAssignmentRecord" }, { "type": "null" } ] }, "bookingLink": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionBookingLinkRecord" }, { "type": "null" } ] }, "membershipLink": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionMembershipLinkRecord" }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "revision": { "type": "integer", "minimum": 1 }, "configurationVersion": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "source": { "type": "string", "minLength": 1, "maxLength": 80 }, "lossReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "intakeNoticeVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "intakeLocale": { "anyOf": [ { "type": "string", "enum": [ "de", "en" ] }, { "type": "null" } ] }, "inquiryRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "marketingEmailRequested": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionHistoryRecord" }, "maxItems": 100 } }, "required": [ "assignment", "bookingLink", "membershipLink", "id", "tenantId", "contactId", "serviceId", "stage", "revision", "configurationVersion", "source", "lossReason", "createdAt", "updatedAt", "intakeNoticeVersion", "intakeLocale", "inquiryRequestedAt", "marketingEmailRequested", "history" ] }, "PublicInterestForm": { "type": "object", "additionalProperties": false, "properties": { "tenantSlug": { "type": "string", "minLength": 1, "maxLength": 80 }, "tenantName": { "type": "string", "minLength": 1, "maxLength": 160 }, "service": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "locationName": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id", "name", "description", "locationName" ] }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "noticeVersion": { "type": "string", "const": "vsm-interest-inquiry-v1" }, "privacyUrl": { "type": "string", "const": "/legal/datenschutz" }, "token": { "type": "string", "minLength": 1, "maxLength": 2048 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "tenantSlug", "tenantName", "service", "locale", "noticeVersion", "privacyUrl", "token", "expiresAt" ] }, "PublicInterestInput": { "type": "object", "additionalProperties": false, "properties": { "contact": { "$ref": "#/components/schemas/AcquisitionContactInput" }, "purpose": { "type": "string", "const": "offerInquiry" }, "marketingEmailRequested": { "type": "boolean" }, "website": { "type": "string", "maxLength": 160 }, "attribution": { "type": "object", "additionalProperties": false, "properties": { "utmSource": { "type": "string", "maxLength": 200 }, "utmMedium": { "type": "string", "maxLength": 200 }, "utmCampaign": { "type": "string", "maxLength": 200 }, "landing": { "type": "string", "maxLength": 200 }, "referrerHost": { "type": "string", "maxLength": 253 } } } }, "required": [ "contact", "purpose", "marketingEmailRequested" ] }, "PublicInterestReceipt": { "type": "object", "additionalProperties": false, "properties": { "received": { "type": "boolean", "const": true } }, "required": [ "received" ] }, "PublicInterestFormEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PublicInterestForm" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "PublicInterestReceiptEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PublicInterestReceipt" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionIntake": { "type": "object", "additionalProperties": false, "properties": { "noticeVersion": { "type": "string", "const": "vsm-interest-inquiry-v1" }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "purpose": { "type": "string", "const": "offerInquiry" }, "requestedAt": { "type": "string", "format": "date-time" }, "marketingEmailRequested": { "type": "boolean" }, "verified": { "type": "boolean", "const": false } }, "required": [ "noticeVersion", "locale", "purpose", "requestedAt", "marketingEmailRequested", "verified" ] }, "AcquisitionBookingOption": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "revision", "status", "startsAt", "endsAt" ] }, "AcquisitionBookingView": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "cancelled", "noShow", "completed" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "linkedAt": { "type": "string", "format": "date-time" }, "matches": { "type": "boolean" }, "processedRevision": { "type": "integer", "minimum": 0 } }, "required": [ "id", "revision", "status", "startsAt", "endsAt", "linkedAt", "matches", "processedRevision" ] }, "AcquisitionBookingLinkRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 128 }, "processedRevision": { "type": "integer", "minimum": 0 }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "leadId", "bookingId", "processedRevision", "linkedAt" ] }, "AcquisitionBookingOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionBookingOption" }, "maxItems": 30 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionBookingOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionBookingOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionLinkBookingInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedBookingRevision": { "type": "integer", "minimum": 0 } }, "required": [ "expectedRevision", "bookingId", "expectedBookingRevision" ] }, "AcquisitionBookingPolicy": { "type": "object", "additionalProperties": false, "properties": { "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 } }, "required": [ "serviceId", "enabled", "revision" ] }, "AcquisitionBookingPolicyInput": { "type": "object", "additionalProperties": false, "properties": { "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 0 } }, "required": [ "serviceId", "enabled", "expectedRevision" ] }, "AcquisitionBookingPolicyResult": { "type": "object", "additionalProperties": false, "properties": { "policy": { "$ref": "#/components/schemas/AcquisitionBookingPolicy" }, "summary": { "type": "object", "additionalProperties": false, "properties": { "pending": { "type": "integer", "minimum": 0 }, "captured": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "captured", "skipped" ] } }, "required": [ "policy", "summary" ] }, "AcquisitionBookingPolicyCommandResult": { "type": "object", "additionalProperties": false, "properties": { "policy": { "$ref": "#/components/schemas/AcquisitionBookingPolicy" }, "summary": { "type": "object", "additionalProperties": false, "properties": { "pending": { "type": "integer", "minimum": 0 }, "captured": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "captured", "skipped" ] }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "policy", "summary", "replayed", "acceptedRevision" ] }, "AcquisitionBookingPolicyEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionBookingPolicyResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionBookingPolicyCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionBookingPolicyCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionBookingCaptureRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 128 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "sourceRevision": { "type": "integer", "minimum": 0 }, "policyRevision": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "PENDING", "CAPTURED", "SKIPPED" ] }, "skipCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "processedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "bookingId", "serviceId", "sourceRevision", "policyRevision", "state", "skipCode", "createdAt", "processedAt" ] }, "AcquisitionMembershipOption": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "updatedAt": { "type": "string", "format": "date-time" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "active", "past_due", "paused", "cancelled", "expired" ] }, "priceMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": [ "id", "updatedAt", "title", "status", "priceMinor", "currency" ] }, "AcquisitionMembershipOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionMembershipOption" }, "maxItems": 30 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionMembershipOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionMembershipOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionLinkMembershipInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "subscriptionId", "expectedUpdatedAt" ] }, "AcquisitionMembershipView": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "updatedAt": { "type": "string", "format": "date-time" }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "active", "past_due", "paused", "cancelled", "expired" ] }, "priceMinor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 1, "maxLength": 3 }, "linkedAt": { "type": "string", "format": "date-time" }, "matches": { "type": "boolean" }, "outcomeApplied": { "type": "boolean" }, "payment": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "invoiceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "paidAt": { "type": "string", "format": "date-time" }, "amountPaidMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": [ "invoiceId", "paidAt", "amountPaidMinor", "currency" ] }, { "type": "null" } ] } }, "required": [ "id", "updatedAt", "title", "status", "priceMinor", "currency", "linkedAt", "matches", "outcomeApplied", "payment" ] }, "AcquisitionMembershipLinkRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "subscriptionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "invoiceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "stageBeforeWin": { "anyOf": [ { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, { "type": "null" } ] }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "leadId", "subscriptionId", "invoiceId", "stageBeforeWin", "linkedAt" ] }, "AcquisitionCustomerOption": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 320 }, "updatedAt": { "type": "string", "format": "date-time" }, "matchedBy": { "type": "string", "enum": [ "email", "phone", "emailAndPhone" ] } }, "required": [ "id", "displayName", "updatedAt", "matchedBy" ] }, "AcquisitionCustomerOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionCustomerOption" }, "maxItems": 30 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionCustomerOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionCustomerOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionLinkCustomerInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "expectedContactUpdatedAt": { "type": "string", "format": "date-time" }, "customerId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "method": { "type": "string", "const": "inPersonConfirmation" }, "confirmed": { "type": "boolean", "const": true } }, "required": [ "expectedRevision", "expectedContactUpdatedAt", "customerId", "expectedUpdatedAt", "method", "confirmed" ] }, "AcquisitionUnlinkCustomerInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "expectedContactUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "expectedContactUpdatedAt" ] }, "AcquisitionMergeOption": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "updatedAt": { "type": "string", "format": "date-time" }, "ways": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "sourceContactId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "kind", "value", "sourceContactId" ] }, "maxItems": 20 }, "opportunityCount": { "type": "integer", "minimum": 1 } }, "required": [ "id", "displayName", "updatedAt", "ways", "opportunityCount" ] }, "AcquisitionMergeOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionMergeOption" }, "maxItems": 30 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionMergeOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionMergeOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionMergePreview": { "type": "object", "additionalProperties": false, "properties": { "source": { "$ref": "#/components/schemas/AcquisitionMergeOption" }, "target": { "$ref": "#/components/schemas/AcquisitionMergeOption" }, "combinedOpportunityCount": { "type": "integer", "minimum": 2, "maximum": 100 }, "retainedWays": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "sourceContactId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "kind", "value", "sourceContactId" ] }, "maxItems": 20 }, "canonicalCustomerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "source", "target", "combinedOpportunityCount", "retainedWays", "canonicalCustomerId" ] }, "AcquisitionMergePreviewEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionMergePreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionMergeContactInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "expectedContactUpdatedAt": { "type": "string", "format": "date-time" }, "targetContactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedTargetUpdatedAt": { "type": "string", "format": "date-time" }, "confirmed": { "type": "boolean", "const": true } }, "required": [ "expectedRevision", "expectedContactUpdatedAt", "targetContactId", "expectedTargetUpdatedAt", "confirmed" ] }, "AcquisitionPhaseDefinition": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "labels": { "type": "object", "additionalProperties": false, "properties": { "de": { "type": "string", "minLength": 1, "maxLength": 64 }, "en": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "de", "en" ] } }, "required": [ "id", "labels" ] }, "AcquisitionPhaseConfiguration": { "type": "object", "additionalProperties": false, "properties": { "contractVersion": { "type": "string", "const": "vsm-acquisition-phase-configuration-v1" }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionPhaseDefinition" }, "maxItems": 7, "minItems": 7 } }, "required": [ "contractVersion", "version", "createdAt", "stages" ] }, "AcquisitionPhaseConfigurationInput": { "type": "object", "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionPhaseDefinition" }, "maxItems": 7, "minItems": 7 } }, "required": [ "expectedVersion", "stages" ] }, "AcquisitionPhaseConfigurationCommandResult": { "type": "object", "additionalProperties": false, "properties": { "configuration": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" }, "replayed": { "type": "boolean" }, "acceptedVersion": { "type": "integer", "minimum": 2 } }, "required": [ "configuration", "replayed", "acceptedVersion" ] }, "AcquisitionPhaseConfigurationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionPhaseConfigurationCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionPhaseConfigurationCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionAssignment": { "type": "object", "additionalProperties": false, "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "assignedAt": { "type": "string", "format": "date-time" }, "available": { "type": "boolean" } }, "required": [ "memberId", "displayName", "assignedAt", "available" ] }, "AcquisitionAssignmentRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "assignedAt": { "type": "string", "format": "date-time" }, "suspendedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "leadId", "memberId", "assignedAt", "suspendedAt" ] }, "AcquisitionAssigneeOptions": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "role": { "type": "string", "enum": [ "owner", "manager", "staff" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "displayName", "role", "updatedAt" ] }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionAssigneeOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionAssigneeOptions" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionAssignmentInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "memberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "expectedMemberUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "memberId" ], "oneOf": [ { "properties": { "memberId": { "type": "null" } }, "not": { "required": [ "expectedMemberUpdatedAt" ] } }, { "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "expectedMemberUpdatedAt" ] } ] }, "AcquisitionWorkItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "lossReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "assignedAt": { "type": "string", "format": "date-time" }, "contact": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "ways": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 } }, "required": [ "kind", "value" ] }, "maxItems": 20 } }, "required": [ "displayName", "ways" ] }, "service": { "$ref": "#/components/schemas/AcquisitionOffer" }, "allowedActions": { "type": "array", "items": { "type": "string", "enum": [ "contacted", "offered", "close", "reopen" ] }, "maxItems": 2 } }, "required": [ "id", "revision", "stage", "lossReason", "updatedAt", "assignedAt", "contact", "service", "allowedActions" ] }, "AcquisitionWorkPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionWorkItem" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "configuration": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" } }, "required": [ "items", "nextCursor", "configuration" ] }, "AcquisitionWorkPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionWorkPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionWorkDetail": { "type": "object", "additionalProperties": false, "properties": { "lead": { "$ref": "#/components/schemas/AcquisitionWorkItem" }, "configuration": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" } }, "required": [ "lead", "configuration" ] }, "AcquisitionWorkDetailEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionWorkDetail" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionWorkCommandResult": { "type": "object", "additionalProperties": false, "properties": { "lead": { "$ref": "#/components/schemas/AcquisitionWorkItem" }, "configuration": { "$ref": "#/components/schemas/AcquisitionPhaseConfiguration" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1 } }, "required": [ "lead", "configuration", "replayed", "acceptedRevision" ] }, "AcquisitionWorkCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionWorkCommandResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskHistoryRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "taskId": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "action": { "type": "string", "minLength": 1, "maxLength": 80 }, "state": { "type": "string", "enum": [ "open", "assigned", "completed", "cancelled" ] }, "actorUserId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "memberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "dueAt": { "type": "string", "format": "date-time" }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "reached", "unreachable", "notInterested", "appointmentAgreed" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "taskId", "revision", "action", "state", "actorUserId", "memberId", "dueAt", "outcome", "note", "occurredAt" ] }, "AcquisitionTaskRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceKey": { "type": "string", "minLength": 1, "maxLength": 191 }, "sourceHash": { "type": "string", "minLength": 1, "maxLength": 64 }, "state": { "type": "string", "enum": [ "open", "assigned", "completed", "cancelled" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "dueAt": { "type": "string", "format": "date-time" }, "memberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "autoAssign": { "type": "boolean" }, "nextAssignmentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "assignedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "assignmentLostAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "reached", "unreachable", "notInterested", "appointmentAgreed" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "followUpId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTaskHistoryRecord" }, "maxItems": 100 } }, "required": [ "id", "tenantId", "leadId", "locationId", "title", "sourceKey", "sourceHash", "state", "revision", "dueAt", "memberId", "autoAssign", "nextAssignmentAt", "assignedAt", "assignmentLostAt", "outcome", "note", "completedAt", "followUpId", "createdAt", "updatedAt" ] }, "AcquisitionTask": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "enum": [ "open", "assigned", "completed", "cancelled" ] }, "dueAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "reached", "unreachable", "notInterested", "appointmentAgreed" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "assignmentLostAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "assignee": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "memberId", "displayName" ] }, { "type": "null" } ] }, "contact": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "phones": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 }, "maxItems": 20 } }, "required": [ "displayName", "phones" ] }, "service": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locationName": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id", "name", "locationId", "locationName" ] }, "stage": { "type": "string", "enum": [ "new", "contacted", "appointment", "attended", "offered", "won", "lost" ] }, "phaseSuggestion": { "anyOf": [ { "type": "string", "enum": [ "contacted", "offered" ] }, { "type": "null" } ] }, "leadWorkAllowed": { "type": "boolean" }, "allowedActions": { "type": "array", "items": { "type": "string", "enum": [ "assign", "claim", "snooze", "complete", "cancel" ] }, "maxItems": 5 } }, "required": [ "id", "leadId", "revision", "title", "state", "dueAt", "createdAt", "updatedAt", "completedAt", "outcome", "note", "assignmentLostAt", "assignee", "contact", "service", "stage", "phaseSuggestion", "leadWorkAllowed", "allowedActions" ] }, "AcquisitionTaskEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTask" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTask" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "items", "nextCursor", "total" ] }, "AcquisitionTaskPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskCommand": { "type": "object", "additionalProperties": false, "properties": { "task": { "$ref": "#/components/schemas/AcquisitionTask" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "followUpId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "task", "replayed", "acceptedRevision", "followUpId" ] }, "AcquisitionTaskCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskCommand" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskCreateInput": { "type": "object", "additionalProperties": false, "properties": { "leadId": { "type": "string", "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "dueAt": { "type": "string", "format": "date-time" }, "assignment": { "type": "string", "enum": [ "open", "automatic" ] }, "sourceKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9:._/-]{1,128}$" } }, "required": [ "leadId", "title", "dueAt", "assignment" ] }, "AcquisitionTaskAssignInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "memberId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "expectedMemberUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "memberId" ], "oneOf": [ { "properties": { "memberId": { "type": "null" } }, "not": { "required": [ "expectedMemberUpdatedAt" ] } }, { "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "expectedMemberUpdatedAt" ] } ] }, "AcquisitionTaskClaimInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "expectedRevision" ] }, "AcquisitionTaskCancelInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "expectedRevision" ] }, "AcquisitionTaskSnoozeInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "dueAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "dueAt" ] }, "AcquisitionTaskCompleteInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "outcome": { "type": "string", "enum": [ "reached", "unreachable", "notInterested", "appointmentAgreed" ] }, "note": { "type": "string", "maxLength": 500 }, "followUpDueAt": { "type": "string", "format": "date-time" } }, "required": [ "expectedRevision", "outcome" ] }, "AcquisitionTaskCircle": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "locationName": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "integer", "minimum": 0, "maximum": 2147483646 }, "automaticAssignment": { "type": "boolean" }, "createOnNewLead": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "members": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "updatedAt": { "type": "string", "format": "date-time" }, "available": { "type": "boolean" } }, "required": [ "memberId", "displayName", "updatedAt", "available" ] }, "maxItems": 100 } }, "required": [ "locationId", "locationName", "revision", "automaticAssignment", "createOnNewLead", "delayMinutes", "members" ] }, "AcquisitionTaskCircleEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskCircle" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskCircleInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 2147483646 }, "automaticAssignment": { "type": "boolean" }, "createOnNewLead": { "type": "boolean" }, "delayMinutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "members": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedMemberUpdatedAt": { "type": "string", "format": "date-time" } }, "required": [ "memberId", "expectedMemberUpdatedAt" ] }, "maxItems": 100 } }, "required": [ "expectedRevision", "automaticAssignment", "createOnNewLead", "delayMinutes", "members" ] }, "AcquisitionTaskCircleCommand": { "type": "object", "additionalProperties": false, "properties": { "circle": { "$ref": "#/components/schemas/AcquisitionTaskCircle" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "circle", "replayed", "acceptedRevision" ] }, "AcquisitionTaskCircleCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskCircleCommand" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskMember": { "type": "object", "additionalProperties": false, "properties": { "memberId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "memberId", "displayName", "updatedAt" ] }, "AcquisitionTaskMemberPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AcquisitionTaskMember" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionTaskMemberPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskMemberPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "AcquisitionTaskLocationPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id", "name" ] }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "AcquisitionTaskLocationPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AcquisitionTaskLocationPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "birthDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "archived" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "displayName", "birthDate", "state", "revision", "createdAt", "updatedAt" ] }, "PersonalFamilyParticipant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "birthDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "archived" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "representationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "book", "manage" ] }, "maxItems": 3, "minItems": 1, "uniqueItems": true } }, "required": [ "id", "displayName", "birthDate", "state", "revision", "createdAt", "updatedAt", "representationId", "scopes" ] }, "FamilyParticipantPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyParticipant" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "PersonalFamilyParticipantPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalFamilyParticipant" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "FamilyParticipantCommand": { "type": "object", "additionalProperties": false, "properties": { "result": { "$ref": "#/components/schemas/FamilyParticipant" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "result", "replayed", "acceptedRevision" ] }, "FamilyRepresentation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "participantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 128 }, "state": { "type": "string", "enum": [ "pending", "active", "revoked" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "book", "manage" ] }, "maxItems": 3, "minItems": 1, "uniqueItems": true }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "verificationMethod": { "anyOf": [ { "type": "string", "const": "operator-confirmation" }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "participantId", "customerId", "state", "scopes", "revision", "verificationMethod", "verifiedAt", "revokedAt" ] }, "FamilyRepresentationPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyRepresentationListItem" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "FamilyRepresentationCommand": { "type": "object", "additionalProperties": false, "properties": { "result": { "$ref": "#/components/schemas/FamilyRepresentation" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "result", "replayed", "acceptedRevision" ] }, "FamilyParticipantCreateInput": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "birthDate": { "type": "string", "format": "date" } }, "required": [ "displayName" ] }, "FamilyRepresentationInput": { "type": "object", "additionalProperties": false, "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 128 }, "expectedCustomerUpdatedAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "book", "manage" ] }, "maxItems": 3, "minItems": 1, "uniqueItems": true } }, "required": [ "customerId", "expectedCustomerUpdatedAt", "scopes" ] }, "FamilyRepresentationConfirmInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "verificationReference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$" } }, "required": [ "expectedRevision", "verificationReference" ] }, "FamilyRepresentationRevokeInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "expectedRevision" ] }, "FamilyParticipantPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyParticipantPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipantCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyParticipantCommand" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipantEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyParticipant" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyRepresentationPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyRepresentationPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyRepresentationCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyRepresentationCommand" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "PersonalFamilyParticipantPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalFamilyParticipantPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "PersonalFamilyParticipantEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalFamilyParticipant" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyRepresentativeOption": { "type": "object", "additionalProperties": false, "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 128 }, "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "customerId", "displayName", "primaryEmail", "updatedAt" ] }, "FamilyRepresentativeOptionPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyRepresentativeOption" }, "maxItems": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] }, "FamilyRepresentationListItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "participantId": { "type": "string", "minLength": 1, "maxLength": 128 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 128 }, "state": { "type": "string", "enum": [ "pending", "active", "revoked" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "book", "manage" ] }, "maxItems": 3, "minItems": 1, "uniqueItems": true }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "verificationMethod": { "anyOf": [ { "type": "string", "const": "operator-confirmation" }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "primaryEmail": { "type": "string", "format": "email", "maxLength": 320 } }, "required": [ "displayName", "primaryEmail" ] }, { "type": "null" } ] } }, "required": [ "id", "participantId", "customerId", "state", "scopes", "revision", "verificationMethod", "verifiedAt", "revokedAt", "contact" ] }, "FamilyRepresentativeOptionPageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyRepresentativeOptionPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "BookingParticipantSelection": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "none", "partial", "complete" ] }, "participantIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 100, "uniqueItems": true } }, "required": [ "mode", "participantIds" ] }, "FamilyBookingInput": { "type": "object", "additionalProperties": false, "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 128 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 128 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "partySize": { "type": "integer", "minimum": 1, "maximum": 1000 }, "selection": { "$ref": "#/components/schemas/BookingParticipantSelection" }, "membershipId": { "type": "string", "minLength": 1, "maxLength": 128 }, "notes": { "type": "string", "maxLength": 5000 } }, "required": [ "locationId", "calendarId", "startsAt", "endsAt", "partySize", "selection" ] }, "FamilyBookingResult": { "type": "object", "additionalProperties": false, "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "capacity": { "$ref": "#/components/schemas/SlotCapacityDecision" }, "emailMessages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessage" } }, "mail": { "type": "object", "additionalProperties": false, "required": [ "queued" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "skippedReason": { "type": "string", "enum": [ "missingGuestEmail", "unchangedStatus", "statusHasNoCustomerMail" ] } } }, "webhooks": { "$ref": "#/components/schemas/WebhookEnqueueSummary" }, "loyaltyAccrual": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "applied", "pending" ] }, "appended": { "type": "integer", "minimum": 0 }, "deduplicated": { "type": "integer", "minimum": 0 } } }, "selection": { "$ref": "#/components/schemas/BookingParticipantSelection" } }, "required": [ "booking", "emailMessages", "mail", "webhooks", "selection" ] }, "FamilyBookingResultEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyBookingResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipantRevisionInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "expectedRevision" ] }, "FamilyParticipantErasureInput": { "type": "object", "additionalProperties": false, "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "confirm": { "type": "boolean", "const": true } }, "required": [ "expectedRevision", "confirm" ] }, "FamilyParticipantErasure": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "state": { "type": "string", "const": "erased" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "id", "state", "revision" ] }, "FamilyParticipantErasureCommand": { "type": "object", "additionalProperties": false, "properties": { "result": { "$ref": "#/components/schemas/FamilyParticipantErasure" }, "replayed": { "type": "boolean" }, "acceptedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "result", "replayed", "acceptedRevision" ] }, "FamilyParticipantExport": { "type": "object", "additionalProperties": false, "properties": { "contractVersion": { "type": "string", "const": "vsm-family-participant-export-v1" }, "exportedAt": { "type": "string", "format": "date-time" }, "participant": { "$ref": "#/components/schemas/FamilyParticipant" }, "representations": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyRepresentation" }, "maxItems": 1000 }, "workflowEvents": { "type": "array", "items": { "$ref": "#/components/schemas/FamilyWorkflowEvent" }, "maxItems": 1000 }, "bookings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "partySize": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "id", "startsAt", "endsAt", "partySize", "status" ] }, "maxItems": 1000 } }, "required": [ "contractVersion", "exportedAt", "participant", "representations", "workflowEvents", "bookings" ] }, "FamilyParticipantExportEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyParticipantExport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipantErasureCommandEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FamilyParticipantErasureCommand" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "required": [ "data", "meta" ] }, "FamilyParticipantPrivacyExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "displayName", "birthDate", "state", "revision", "erasedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "birthDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "archived", "erased" ] }, "revision": { "type": "integer", "minimum": 1 }, "erasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ParticipantRepresentationPrivacyExport": { "type": "object", "additionalProperties": false, "required": [ "id", "participantId", "customerId", "accountUserId", "state", "scopes", "revision", "verificationMethod", "verifiedAt", "revokedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "participantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 191 }, "accountUserId": { "type": "string", "minLength": 1, "maxLength": 191 }, "state": { "type": "string", "enum": [ "pending", "active", "revoked" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "book", "manage" ] } }, "revision": { "type": "integer", "minimum": 1 }, "verificationMethod": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ParticipantCommandPrivacyExport": { "type": "object", "additionalProperties": false, "required": [ "id", "commandKey", "action", "participantId", "representationId", "acceptedRevision", "erasedAt", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "commandKey": { "type": "string", "format": "uuid" }, "action": { "type": "string", "minLength": 1, "maxLength": 32 }, "participantId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "representationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] }, "acceptedRevision": { "type": "integer", "minimum": 1 }, "erasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "BookingParticipantPrivacyExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "bookingId", "participantId", "representationId", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 191 }, "participantId": { "type": "string", "minLength": 1, "maxLength": 191 }, "representationId": { "type": "string", "minLength": 1, "maxLength": 191 }, "createdAt": { "type": "string", "format": "date-time" } } }, "FamilyWorkflowEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "resourceType": { "type": "string", "enum": [ "familyParticipant", "participantRepresentation" ] }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "resourceRevision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "eventType": { "type": "string", "enum": [ "family.participantCreated", "family.participantUpdated", "family.participantArchived", "family.participantErased", "family.representationProposed", "family.representationConfirmed", "family.representationRevoked" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "active", "archived", "erased", "pending", "revoked" ] } }, "required": [ "state" ] } }, "required": [ "id", "resourceType", "resourceId", "resourceRevision", "eventType", "occurredAt", "payload" ] }, "FamilyTransportHoldPage": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "items", "nextCursor" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "messageId", "bookingId", "claimStartedAt", "heldSince", "evidence", "canResolveWithEvidence", "evidenceBlockedReason", "canAssumeDelivered", "assumeDeliveredAvailableAt" ], "properties": { "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "bookingId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "claimStartedAt": { "type": "string", "format": "date-time" }, "heldSince": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "outcome", "receivedAt", "source" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted" ] }, "receivedAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "const": "signedRelay" } } }, "maxItems": 50 }, "canResolveWithEvidence": { "type": "boolean" }, "evidenceBlockedReason": { "anyOf": [ { "type": "string", "enum": [ "noEvidence", "conflictingEvidence", "positiveTransportFact" ] }, { "type": "null" } ] }, "canAssumeDelivered": { "type": "boolean" }, "assumeDeliveredAvailableAt": { "type": "string", "format": "date-time" } } }, "maxItems": 20 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } } }, "FamilyTransportHoldEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FamilyTransportHoldPage" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "FamilyTransportResolveInput": { "type": "object", "additionalProperties": false, "required": [ "expectedTenantId", "claimStartedAt", "mode", "commandKey", "reason" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "evidence", "assumeDelivered" ] }, "evidenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "commandKey": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } } }, "FamilyTransportResolveResult": { "type": "object", "additionalProperties": false, "required": [ "messageId", "claimStartedAt", "outcome", "evidenceId", "replayed" ], "properties": { "messageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted", "assumedDelivered" ] }, "evidenceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "replayed": { "type": "boolean" } } }, "FamilyTransportResolveEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FamilyTransportResolveResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "FamilyTransportEvidenceExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "emailMessageId", "provider", "providerEventId", "claimStartedAt", "outcome", "version", "payloadDigest", "receiptDigest", "receivedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "provider": { "type": "string", "minLength": 2, "maxLength": 64 }, "providerEventId": { "type": "string", "minLength": 1, "maxLength": 255 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted" ] }, "version": { "type": "string", "const": "vsm-family-transport-receipt-v1" }, "payloadDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "receiptDigest": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time" } } }, "FamilyTransportResolutionExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "emailMessageId", "claimStartedAt", "evidenceId", "outcome", "commandKey", "commandDigest", "actorUserId", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "emailMessageId": { "type": "string", "minLength": 1, "maxLength": 160 }, "claimStartedAt": { "type": "string", "format": "date-time" }, "evidenceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": [ "accepted", "notAccepted", "assumedDelivered" ] }, "commandKey": { "type": "string", "minLength": 8, "maxLength": 64 }, "commandDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "actorUserId": { "type": "string", "minLength": 1, "maxLength": 160 }, "createdAt": { "type": "string", "format": "date-time" } } }, "CommunicationUsageWarningExport": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "unit", "periodStart", "thresholdPercent", "usedAtCrossing", "limitAtCrossing", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "unit": { "type": "string", "minLength": 1, "maxLength": 64 }, "periodStart": { "type": "string", "format": "date-time" }, "thresholdPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "usedAtCrossing": { "type": "integer", "minimum": 0 }, "limitAtCrossing": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } } }, "ConversationAssignmentInput": { "type": "object", "additionalProperties": false, "required": [ "assigneeUserId", "expectedRevision" ], "properties": { "assigneeUserId": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } } }, "GrowthFunnelQueryInput": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "minLength": 1, "maxLength": 80 } }, "additionalProperties": false }, "GrowthFunnelReport": { "type": "object", "required": [ "contractVersion", "tenantId", "generatedAt", "timezone", "period", "filters", "cohort", "events" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-growth-funnel-v1" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "generatedAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "filters": { "type": "object", "required": [ "serviceId", "locationId", "source" ], "properties": { "serviceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] } }, "additionalProperties": false }, "cohort": { "type": "object", "required": [ "opportunities", "contacts", "linkedParticipants", "stages", "outcomes", "confirmedRevenue", "sources", "limitedSignificance", "truncated" ], "properties": { "opportunities": { "type": "integer", "minimum": 0 }, "contacts": { "type": "integer", "minimum": 0 }, "linkedParticipants": { "type": "integer", "minimum": 0 }, "stages": { "type": "array", "items": { "type": "object", "required": [ "key", "count", "fromPrevious", "fromCohort" ], "properties": { "key": { "type": "string", "enum": [ "opportunities", "contacted", "appointmentBooked", "attended", "wonConfirmed" ] }, "count": { "type": "integer", "minimum": 0 }, "fromPrevious": { "type": "object", "required": [ "numerator", "denominator", "rate" ], "properties": { "numerator": { "type": "integer", "minimum": 0 }, "denominator": { "type": "integer", "minimum": 0 }, "rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "additionalProperties": false }, "fromCohort": { "type": "object", "required": [ "numerator", "denominator", "rate" ], "properties": { "numerator": { "type": "integer", "minimum": 0 }, "denominator": { "type": "integer", "minimum": 0 }, "rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "minItems": 0 }, "outcomes": { "type": "object", "required": [ "cancelled", "noShow", "rebooked", "wonUnconfirmed", "lost", "open" ], "properties": { "cancelled": { "type": "integer", "minimum": 0 }, "noShow": { "type": "integer", "minimum": 0 }, "rebooked": { "type": "integer", "minimum": 0 }, "wonUnconfirmed": { "type": "integer", "minimum": 0 }, "lost": { "type": "integer", "minimum": 0 }, "open": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "confirmedRevenue": { "type": "array", "items": { "type": "object", "required": [ "currency", "amountMinor", "wins" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "integer", "minimum": 0 }, "wins": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "minItems": 0 }, "sources": { "type": "array", "items": { "type": "object", "required": [ "source", "opportunities", "wonConfirmed" ], "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 80 }, "opportunities": { "type": "integer", "minimum": 0 }, "wonConfirmed": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "minItems": 0 }, "limitedSignificance": { "type": "boolean" }, "truncated": { "type": "boolean" } }, "additionalProperties": false }, "events": { "type": "object", "required": [ "opportunitiesCreated", "bookingsLinked", "winsConfirmed", "lost" ], "properties": { "opportunitiesCreated": { "type": "integer", "minimum": 0 }, "bookingsLinked": { "type": "integer", "minimum": 0 }, "winsConfirmed": { "type": "integer", "minimum": 0 }, "lost": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false }, "GrowthFunnelEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/GrowthFunnelReport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "NextActionsReport": { "type": "object", "required": [ "contractVersion", "tenantId", "generatedAt", "scope", "items" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-next-actions-v1" }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "generatedAt": { "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "own", "team" ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "kind", "priority", "count", "denominator", "windowDays", "minimumSample", "significance", "href" ], "properties": { "kind": { "type": "string", "enum": [ "overdueCallbacks", "unansweredMessages", "highNoShowShare", "incompleteConfiguration" ] }, "priority": { "type": "integer", "minimum": 1 }, "count": { "type": "integer", "minimum": 0 }, "denominator": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "windowDays": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "minimumSample": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "significance": { "type": "string", "enum": [ "sufficient", "limited" ] }, "href": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "minItems": 0, "maxItems": 3 } }, "additionalProperties": false }, "NextActionsEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/NextActionsReport" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "WaitlistGroupCallInput": { "type": "object", "additionalProperties": false, "required": [ "slotId", "previewHash" ], "properties": { "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "durationMinutes": { "type": "integer", "minimum": 15, "maximum": 10080 } } }, "WaitlistGroupCallResult": { "type": "object", "additionalProperties": false, "required": [ "groupCallId", "recipientCount", "expiresAt", "replayed" ], "properties": { "groupCallId": { "type": "string", "minLength": 1, "maxLength": 160 }, "recipientCount": { "type": "integer", "minimum": 1, "maximum": 100 }, "expiresAt": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean" } } }, "WaitlistGroupCallEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WaitlistGroupCallResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "WaitlistGroupCallPreview": { "type": "object", "additionalProperties": false, "required": [ "slotId", "capacity", "reserved", "available", "activeGroupCallExpiresAt", "recipients", "tooLarge", "previewHash", "blockedReason" ], "properties": { "slotId": { "type": "string", "minLength": 1, "maxLength": 160 }, "capacity": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "activeGroupCallExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recipients": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "entryId", "position", "guestName", "partySize" ], "properties": { "entryId": { "type": "string", "minLength": 1, "maxLength": 160 }, "position": { "type": "integer", "minimum": 1 }, "guestName": { "type": "string", "minLength": 1, "maxLength": 160 }, "partySize": { "type": "integer", "minimum": 1 } } } }, "tooLarge": { "type": "integer", "minimum": 0 }, "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "blockedReason": { "anyOf": [ { "type": "string", "enum": [ "slotUnavailable", "groupCallActive", "exclusiveOfferActive", "noCapacity", "noEligibleEntries" ] }, { "type": "null" } ] } } }, "WaitlistGroupCallPreviewEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WaitlistGroupCallPreview" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "PublicWaitlistClaimResult": { "type": "object", "additionalProperties": false, "required": [ "status", "bookingId", "replayed" ], "properties": { "status": { "type": "string", "const": "booked" }, "bookingId": { "type": "string", "minLength": 1, "maxLength": 160 }, "replayed": { "type": "boolean" } } }, "PublicWaitlistClaimEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PublicWaitlistClaimResult" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "HolidayImportInput": { "type": "object", "required": [ "action", "calendarId", "year" ], "properties": { "action": { "type": "string", "enum": [ "preview", "apply", "rollback" ] }, "kind": { "type": "string", "enum": [ "public", "school", "upload" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "enum": [ "BW", "BY", "BE", "BB", "HB", "HH", "HE", "MV", "NI", "NW", "RP", "SL", "SN", "ST", "SH", "TH" ] }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "locale": { "type": "string", "enum": [ "de", "en" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "expectedSourceHash": { "type": "string", "minLength": 64, "maxLength": 64 } }, "additionalProperties": false }, "HolidayImportPlan": { "type": "object", "required": [ "calendarId", "kind", "state", "year", "source", "sourceHash", "expectedUpdatedAt", "add", "change", "unchanged", "remove", "conflicts" ], "properties": { "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "public", "school", "upload" ] }, "state": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "source": { "type": "string", "enum": [ "vsm-holidays-de-v1", "openholidays-school-v1", "vsm-holiday-upload-v1" ] }, "sourceHash": { "type": "string", "minLength": 64, "maxLength": 64 }, "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "add": { "type": "array", "items": { "type": "object", "required": [ "date", "name" ], "properties": { "date": { "type": "string", "minLength": 10, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "minItems": 0 }, "change": { "type": "array", "items": { "type": "object", "required": [ "date", "name" ], "properties": { "date": { "type": "string", "minLength": 10, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "minItems": 0 }, "unchanged": { "type": "integer", "minimum": 0 }, "remove": { "type": "array", "items": { "type": "object", "required": [ "date" ], "properties": { "date": { "type": "string", "minLength": 10, "maxLength": 10 } }, "additionalProperties": false }, "minItems": 0 }, "conflicts": { "type": "array", "items": { "type": "object", "required": [ "date", "name", "kind" ], "properties": { "date": { "type": "string", "minLength": 10, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "manualException", "otherImport", "bookings" ] }, "bookings": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "minItems": 0 }, "applied": { "type": "boolean" } }, "additionalProperties": false }, "HolidayImportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/HolidayImportPlan" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "LandingPageContent": { "type": "object", "required": [ "title", "intro", "ctaLabel" ], "properties": { "locale": { "type": "string", "enum": [ "de", "en" ] }, "title": { "type": "string", "minLength": 3, "maxLength": 120 }, "intro": { "type": "string", "minLength": 10, "maxLength": 300 }, "highlights": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 120 }, "minItems": 0, "maxItems": 5 }, "body": { "type": "string", "minLength": 0, "maxLength": 4000 }, "trustNote": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 300 }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string", "minLength": 6, "maxLength": 32 }, { "type": "null" } ] }, "mediaAssetId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "mediaAlt": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] }, "ctaLabel": { "type": "string", "minLength": 2, "maxLength": 60 }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 70 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 170 }, { "type": "null" } ] } }, "additionalProperties": false }, "LandingPageSource": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "calendar", "eventOffering" ] }, "calendarId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "eventId": { "type": "string", "minLength": 1, "maxLength": 160 }, "offeringId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false }, "LandingPageCreateInput": { "type": "object", "required": [ "slug", "source", "content" ], "properties": { "slug": { "type": "string", "minLength": 3, "maxLength": 80 }, "source": { "$ref": "#/components/schemas/LandingPageSource" }, "content": { "$ref": "#/components/schemas/LandingPageContent" } }, "additionalProperties": false }, "LandingPageDraftInput": { "type": "object", "required": [ "expectedRevision", "content" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "content": { "$ref": "#/components/schemas/LandingPageContent" } }, "additionalProperties": false }, "LandingPageCommandInput": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "LandingPage": { "type": "object", "required": [ "id", "slug", "status", "revision", "source", "draft", "published", "publicPath", "publishedAt", "archivedAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 3, "maxLength": 80 }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "revision": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/LandingPageSource" }, "draft": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "published": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "publicPath": { "type": "string", "minLength": 1, "maxLength": 300 }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "LandingPageEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "page" ], "properties": { "page": { "$ref": "#/components/schemas/LandingPage" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "LandingPageListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "pages" ], "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPage" }, "minItems": 0, "maxItems": 100 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "LandingPageMediaOptionsEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "mimeType", "previewPath", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "width": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "altText": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 300 }, { "type": "null" } ] }, "previewPath": { "type": "string", "minLength": 1, "maxLength": 300 }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "minItems": 0, "maxItems": 60 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "LandingPageMediaArtifact": { "type": "string", "format": "binary" }, "PublicLandingPageEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "page" ], "properties": { "page": { "type": "object", "required": [ "contractVersion", "tenantSlug", "slug", "content", "offering", "cta", "privacyPath", "canonicalPath" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-landing-page-v1" }, "tenantSlug": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 3, "maxLength": 80 }, "content": { "type": "object", "additionalProperties": true }, "offering": { "type": "object", "required": [ "kind", "name", "locationName" ], "properties": { "kind": { "type": "string", "enum": [ "calendar", "eventOffering" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "locationName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "additionalProperties": false }, "cta": { "type": "object", "required": [ "href", "label" ], "properties": { "href": { "type": "string", "minLength": 1, "maxLength": 600 }, "label": { "type": "string", "minLength": 2, "maxLength": 60 } }, "additionalProperties": false }, "privacyPath": { "type": "string", "minLength": 1, "maxLength": 300 }, "canonicalPath": { "type": "string", "minLength": 1, "maxLength": 300 } }, "additionalProperties": false } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpStep": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "wait", "message", "task" ] }, "waitHours": { "type": "integer", "minimum": 1, "maximum": 2160 }, "subject": { "type": "string", "minLength": 3, "maxLength": 160 }, "body": { "type": "string", "minLength": 10, "maxLength": 4000 }, "taskTitle": { "type": "string", "minLength": 3, "maxLength": 160 }, "dueInHours": { "type": "integer", "minimum": 0, "maximum": 720 } }, "additionalProperties": false }, "FollowUpDefinition": { "type": "object", "required": [ "name", "purpose", "trigger", "steps" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "purpose": { "type": "string", "enum": [ "service", "reactivation" ] }, "trigger": { "type": "string", "enum": [ "leadCreated", "appointmentBooked", "manual" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpStep" }, "minItems": 0, "maxItems": 8 } }, "additionalProperties": false }, "FollowUpSequenceCreateInput": { "type": "object", "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/FollowUpDefinition" } }, "additionalProperties": false }, "FollowUpSequenceReviseInput": { "type": "object", "required": [ "expectedRevision", "definition" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "definition": { "$ref": "#/components/schemas/FollowUpDefinition" } }, "additionalProperties": false }, "FollowUpSequenceStatusInput": { "type": "object", "required": [ "expectedRevision", "status" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] } }, "additionalProperties": false }, "FollowUpMigrateInput": { "type": "object", "required": [ "expectedRevision", "apply" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "apply": { "type": "boolean" } }, "additionalProperties": false }, "FollowUpEnrollInput": { "type": "object", "required": [ "inactiveDays", "expectedRecipients" ], "properties": { "inactiveDays": { "type": "integer", "minimum": 30, "maximum": 730 }, "expectedRecipients": { "type": "integer", "minimum": 0, "maximum": 500 } }, "additionalProperties": false }, "FollowUpEnrollmentCommandInput": { "type": "object", "required": [ "action", "expectedRevision" ], "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "stop", "replied", "snooze" ] }, "expectedRevision": { "type": "integer", "minimum": 1 }, "snoozeHours": { "type": "integer", "minimum": 1, "maximum": 720 } }, "additionalProperties": false }, "FollowUpSequence": { "type": "object", "required": [ "id", "name", "purpose", "trigger", "status", "revision", "version", "steps", "enrollments", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 3, "maxLength": 120 }, "purpose": { "type": "string", "enum": [ "service", "reactivation" ] }, "trigger": { "type": "string", "enum": [ "leadCreated", "appointmentBooked", "manual" ] }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "revision": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpStep" }, "minItems": 0, "maxItems": 8 }, "enrollments": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "FollowUpSequenceEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sequence" ], "properties": { "sequence": { "$ref": "#/components/schemas/FollowUpSequence" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpSequenceListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sequences" ], "properties": { "sequences": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpSequence" }, "minItems": 0, "maxItems": 50 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpMigrationEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "toVersion", "enrollments", "finishingImmediately", "applied" ], "properties": { "toVersion": { "type": "integer", "minimum": 1 }, "enrollments": { "type": "integer", "minimum": 0 }, "finishingImmediately": { "type": "integer", "minimum": 0 }, "applied": { "type": "boolean" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpPreviewEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "purpose", "channels", "recipients", "truncated", "excludedSuppressed", "estimatedMails", "stopRules", "sample" ], "properties": { "purpose": { "type": "string", "enum": [ "service", "reactivation" ] }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email" ] }, "minItems": 0, "maxItems": 3 }, "recipients": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "excludedSuppressed": { "type": "integer", "minimum": 0 }, "estimatedMails": { "type": "integer", "minimum": 0 }, "stopRules": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "minItems": 0, "maxItems": 12 }, "sample": { "type": "array", "items": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] } }, "additionalProperties": false }, "minItems": 0, "maxItems": 5 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpEnrollResultEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "enrolled" ], "properties": { "enrolled": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpEnrollment": { "type": "object", "required": [ "id", "sequenceId", "state", "stopReason", "nextPosition", "nextRunAt", "budgetAttempts", "revision", "enrolledAt", "finishedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "sequenceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "leadId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "paused", "waitingBudget", "completed", "stopped" ] }, "stopReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 24 }, { "type": "null" } ] }, "nextPosition": { "type": "integer", "minimum": 0 }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "budgetAttempts": { "type": "integer", "minimum": 0 }, "revision": { "type": "integer", "minimum": 1 }, "enrolledAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "subjectName": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "required": [ "position", "outcome", "createdAt" ], "properties": { "position": { "type": "integer", "minimum": 0 }, "outcome": { "type": "string", "enum": [ "waited", "sent", "taskCreated" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "minItems": 0, "maxItems": 8 } }, "additionalProperties": false }, "FollowUpEnrollmentEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "enrollment" ], "properties": { "enrollment": { "$ref": "#/components/schemas/FollowUpEnrollment" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "FollowUpEnrollmentListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "enrollments" ], "properties": { "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpEnrollment" }, "minItems": 0, "maxItems": 100 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "AttributionReportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "contractVersion", "period", "model", "truncated", "totals", "rows", "limits" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-attribution-v1" }, "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "model": { "type": "object", "required": [ "firstTouch", "lastNonDirect", "lookbackDays" ], "properties": { "firstTouch": { "type": "string", "const": "first-recorded" }, "lastNonDirect": { "type": "string", "const": "last-non-direct" }, "lookbackDays": { "type": "integer", "minimum": 1, "maximum": 365 } }, "additionalProperties": false }, "truncated": { "type": "boolean" }, "totals": { "type": "object", "required": [ "leads", "bookings" ], "properties": { "leads": { "type": "integer", "minimum": 0 }, "bookings": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "rows": { "type": "array", "items": { "type": "object", "required": [ "label", "leadsFirstTouch", "leadsLastNonDirect", "wonFirstTouch", "wonLastNonDirect", "bookings" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 400 }, "leadsFirstTouch": { "type": "integer", "minimum": 0 }, "leadsLastNonDirect": { "type": "integer", "minimum": 0 }, "wonFirstTouch": { "type": "integer", "minimum": 0 }, "wonLastNonDirect": { "type": "integer", "minimum": 0 }, "bookings": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "minItems": 0, "maxItems": 10000 }, "limits": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 0, "maxItems": 10 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "OperatorPushRegisterInput": { "type": "object", "required": [ "subscription", "categories", "displayName" ], "properties": { "subscription": { "type": "string", "minLength": 32, "maxLength": 4096, "writeOnly": true, "x-vsm-sensitive": true }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "callbacks" ] }, "minItems": 0, "maxItems": 2 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 160 } }, "additionalProperties": false }, "OperatorPushCategoriesInput": { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "callbacks" ] }, "minItems": 0, "maxItems": 2 } }, "additionalProperties": false }, "OperatorPushDevice": { "type": "object", "required": [ "id", "categories", "displayName", "status", "registeredAt", "lastSeenAt", "currentSession", "heldDeliveryCount" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "callbacks" ] }, "minItems": 0, "maxItems": 2 }, "displayName": { "type": "string", "minLength": 0, "maxLength": 160 }, "status": { "type": "string", "enum": [ "active", "revoked", "invalid" ] }, "registeredAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "currentSession": { "type": "boolean" }, "heldDeliveryCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "OperatorPushDeviceEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "device" ], "properties": { "device": { "$ref": "#/components/schemas/OperatorPushDevice" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "OperatorPushDeviceListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "devices" ], "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorPushDevice" }, "minItems": 0, "maxItems": 20 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "AdSpendImportInput": { "type": "object", "required": [ "csv", "apply" ], "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 1000000 }, "apply": { "type": "boolean" } }, "additionalProperties": false }, "AdSpendImportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "rows", "errors", "currencies", "applied" ], "properties": { "rows": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "object", "required": [ "line", "reason" ], "properties": { "line": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 40 } }, "additionalProperties": false }, "minItems": 0, "maxItems": 5000 }, "currencies": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 3 }, "minItems": 0, "maxItems": 50 }, "days": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "minLength": 10, "maxLength": 10 }, "to": { "type": "string", "minLength": 10, "maxLength": 10 } }, "additionalProperties": false }, { "type": "null" } ] }, "applied": { "type": "boolean" }, "replayed": { "type": "boolean" }, "importId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "AdSpendReportEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "contractVersion", "source", "period", "model", "truncated", "rows" ], "properties": { "contractVersion": { "type": "string", "const": "vsm-ad-spend-v1" }, "source": { "type": "string", "const": "manualCsv" }, "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "model": { "type": "object", "required": [ "attribution", "lookbackDays" ], "properties": { "attribution": { "type": "string", "const": "last-non-direct" }, "lookbackDays": { "type": "integer", "minimum": 1, "maximum": 365 } }, "additionalProperties": false }, "truncated": { "type": "boolean" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "campaignKey", "currency", "spendMinor", "wonContacts", "wonOpportunities", "costPerWonContactMinor", "costPerWonOpportunityMinor" ], "properties": { "campaignKey": { "type": "string", "minLength": 1, "maxLength": 80 }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "spendMinor": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "wonContacts": { "type": "integer", "minimum": 0 }, "wonOpportunities": { "type": "integer", "minimum": 0 }, "costPerWonContactMinor": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "costPerWonOpportunityMinor": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false }, "minItems": 0, "maxItems": 10000 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "LandingPageMediaUploadEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "required": [ "id", "mimeType", "previewPath", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "width": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "altText": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 300 }, { "type": "null" } ] }, "previewPath": { "type": "string", "minLength": 1, "maxLength": 300 }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextSender": { "type": "object", "required": [ "id", "channel", "phoneNumber", "label", "status", "revision" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "phoneNumber": { "type": "string", "minLength": 8, "maxLength": 16 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "revision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "TextSenderListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TextSender" }, "minItems": 0, "maxItems": 50 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextSenderEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sender" ], "properties": { "sender": { "$ref": "#/components/schemas/TextSender" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextSenderCreateInput": { "type": "object", "required": [ "channel", "phoneNumber", "label" ], "properties": { "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "phoneNumber": { "type": "string", "minLength": 8, "maxLength": 40 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "TextSenderStatusInput": { "type": "object", "required": [ "status", "expectedRevision" ], "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "TextMessage": { "type": "object", "required": [ "id", "channel", "direction", "status", "threadId", "senderNumber", "counterpartNumber", "body", "segments", "encoding", "failureCode", "createdAt", "sentAt", "deliveredAt", "kind", "template", "media" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "failed", "unknown", "blocked", "received" ] }, "threadId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "senderNumber": { "type": "string", "minLength": 8, "maxLength": 16 }, "counterpartNumber": { "type": "string", "minLength": 8, "maxLength": 16 }, "body": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "segments": { "type": "integer", "minimum": 1, "maximum": 10 }, "encoding": { "type": "string", "minLength": 1, "maxLength": 16 }, "failureCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "freeform", "template" ] }, "template": { "anyOf": [ { "type": "object", "required": [ "id", "contentSid", "version" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "contentSid": { "type": "string", "minLength": 34, "maxLength": 34 }, "version": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, { "type": "null" } ] }, "media": { "type": "array", "items": { "type": "object", "required": [ "id", "position", "contentType", "status", "blockedReason" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "position": { "type": "integer", "minimum": 0, "maximum": 9 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": [ "available", "blocked" ] }, "blockedReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "originalName": { "type": "string", "minLength": 1, "maxLength": 255 }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 16000000 } }, "additionalProperties": false }, "minItems": 0, "maxItems": 10 } }, "additionalProperties": false }, "TextMessageListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TextMessage" }, "minItems": 0, "maxItems": 200 }, "deliveryPaused": { "type": "boolean" }, "whatsappWindow": { "anyOf": [ { "$ref": "#/components/schemas/WhatsAppWindow" }, { "type": "null" } ] } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextMessageEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/TextMessage" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextMessageQueuedEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "message", "replayed" ], "properties": { "message": { "$ref": "#/components/schemas/TextMessage" }, "replayed": { "type": "boolean" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextMessageSendInput": { "type": "object", "required": [ "threadId", "channel" ], "properties": { "threadId": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 }, "senderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "templateId": { "type": "string", "minLength": 1, "maxLength": 160 }, "templateVersion": { "type": "integer", "minimum": 1 }, "variables": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "minItems": 0, "maxItems": 20 } }, "additionalProperties": false }, "TextMessageAssignInput": { "type": "object", "required": [ "threadId" ], "properties": { "threadId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false }, "ServiceRequest": { "type": "object", "required": [ "id", "kind", "message", "contactPreference", "contactPhone", "notified", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "onboarding", "review", "integration" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "contactPreference": { "type": "string", "enum": [ "email", "phone" ] }, "contactPhone": { "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 16 }, { "type": "null" } ] }, "notified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ServiceRequestListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRequest" }, "minItems": 0, "maxItems": 50 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ServiceRequestEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "request", "replayed" ], "properties": { "request": { "$ref": "#/components/schemas/ServiceRequest" }, "replayed": { "type": "boolean" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "ServiceRequestCreateInput": { "type": "object", "required": [ "kind", "message", "contactPreference" ], "properties": { "kind": { "type": "string", "enum": [ "onboarding", "review", "integration" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "contactPreference": { "type": "string", "enum": [ "email", "phone" ] }, "contactPhone": { "type": "string", "minLength": 8, "maxLength": 40 } }, "additionalProperties": false }, "BookingUsagePeriodView": { "type": "object", "additionalProperties": false, "required": [ "unit", "periodStart", "periodEnd", "createdCount", "backfilledCount", "liveCount", "meteringStartedAt", "completeness", "billable", "quotaLimit", "quotaReached" ], "properties": { "unit": { "type": "string", "const": "booking.created" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "createdCount": { "type": "integer", "minimum": 0 }, "backfilledCount": { "type": "integer", "minimum": 0 }, "liveCount": { "type": "integer", "minimum": 0 }, "meteringStartedAt": { "type": "string", "format": "date-time" }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "billable": { "type": "boolean", "const": false }, "quotaLimit": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "quotaReached": { "type": "boolean" } } }, "UsageBillingCorrection": { "type": "object", "required": [ "id", "tenantId", "exportId", "kind", "status", "creditQuantity", "correctedOverageQuantity", "reason", "attempts", "createdAt", "approvable", "cancellable" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "exportId": { "type": "string" }, "kind": { "type": "string", "enum": [ "meter_adjustment", "credit_note" ] }, "status": { "type": "string", "enum": [ "prepared", "executing", "executed", "failed", "cancelled" ] }, "creditQuantity": { "type": "integer", "minimum": 1 }, "correctedOverageQuantity": { "type": "integer", "minimum": 0 }, "reason": { "type": "string" }, "stripeInvoiceId": { "type": [ "string", "null" ] }, "previewAmountMinor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "stripeCreditNoteId": { "type": [ "string", "null" ] }, "replacementIdentifier": { "type": [ "string", "null" ] }, "lastErrorCode": { "type": [ "string", "null" ] }, "attempts": { "type": "integer", "minimum": 0 }, "preparedByUserId": { "type": "string" }, "approvedByUserId": { "type": [ "string", "null" ] }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "approvable": { "type": "boolean" }, "cancellable": { "type": "boolean" }, "stripeMutationAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "UsageBillingCorrectionListEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "items", "permissions" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "tenantId", "unit", "periodStart", "includedQuantity", "consumedQuantity", "overageQuantity", "creditedQuantity", "corrections" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "tenantName": { "type": "string" }, "tenantSlug": { "type": "string" }, "unit": { "type": "string" }, "periodStart": { "type": "string", "format": "date-time" }, "includedQuantity": { "type": "integer" }, "consumedQuantity": { "type": "integer" }, "overageQuantity": { "type": "integer" }, "creditedQuantity": { "type": "integer" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "corrections": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBillingCorrection" } } } } }, "permissions": { "type": "object", "required": [ "write", "approve" ], "properties": { "write": { "type": "boolean" }, "approve": { "type": "boolean" } } } } }, "meta": { "type": "object" } } }, "UsageBillingCorrectionEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsageBillingCorrection" }, "meta": { "type": "object" } } }, "UsageBillingCorrectionApprovalEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "correction", "replayed" ], "properties": { "correction": { "$ref": "#/components/schemas/UsageBillingCorrection" }, "replayed": { "type": "boolean" } } }, "meta": { "type": "object" } } }, "UsageBillingCorrectionPrepareInput": { "type": "object", "additionalProperties": false, "required": [ "exportId", "creditQuantity", "reason" ], "properties": { "exportId": { "type": "string", "minLength": 1, "maxLength": 64 }, "creditQuantity": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "WhatsAppWindow": { "type": "object", "required": [ "open", "lastInboundAt", "closesAt" ], "properties": { "open": { "type": "boolean" }, "lastInboundAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closesAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "additionalProperties": false }, "WhatsAppTemplate": { "type": "object", "required": [ "id", "name", "contentSid", "language", "variableLabels", "previewBody", "category", "approvalStatus", "approvalUpdatedAt", "version", "revision", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contentSid": { "type": "string", "minLength": 34, "maxLength": 34 }, "language": { "type": "string", "minLength": 2, "maxLength": 6 }, "variableLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 0, "maxItems": 20 }, "previewBody": { "type": "string", "minLength": 1, "maxLength": 1024 }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "approvalStatus": { "type": "string", "enum": [ "pending", "approved", "rejected", "paused", "disabled" ] }, "approvalUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "WhatsAppTemplateListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "tenantId", "items", "canManage" ], "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppTemplate" }, "minItems": 0, "maxItems": 200 }, "canManage": { "type": "boolean" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "WhatsAppTemplateEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/WhatsAppTemplate" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "WhatsAppTemplateInput": { "type": "object", "required": [ "expectedTenantId", "name", "contentSid", "language", "category", "variableLabels", "previewBody" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contentSid": { "type": "string", "minLength": 34, "maxLength": 34 }, "language": { "type": "string", "minLength": 2, "maxLength": 6 }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "variableLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 0, "maxItems": 20 }, "previewBody": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "additionalProperties": false }, "WhatsAppTemplateUpdateInput": { "type": "object", "required": [ "expectedTenantId", "name", "contentSid", "language", "category", "variableLabels", "previewBody", "expectedRevision" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contentSid": { "type": "string", "minLength": 34, "maxLength": 34 }, "language": { "type": "string", "minLength": 2, "maxLength": 6 }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "variableLabels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 0, "maxItems": 20 }, "previewBody": { "type": "string", "minLength": 1, "maxLength": 1024 }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "WhatsAppTemplateStatusInput": { "type": "object", "required": [ "expectedTenantId", "status", "expectedRevision" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "paused", "disabled" ] }, "expectedRevision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "TextOptIn": { "type": "object", "required": [ "id", "channel", "phoneNumber", "purpose", "source", "evidence", "capturedAt", "revokedAt", "revokedReason" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "phoneNumber": { "type": "string", "minLength": 8, "maxLength": 16 }, "purpose": { "type": "string", "enum": [ "service", "marketing" ] }, "source": { "type": "string", "enum": [ "form", "operator", "inbound" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 500 }, "capturedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ] } }, "additionalProperties": false }, "TextOptInListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "phoneNumber", "items" ], "properties": { "phoneNumber": { "type": "string", "minLength": 8, "maxLength": 16 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TextOptIn" }, "minItems": 0, "maxItems": 4 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextOptInEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "optIn" ], "properties": { "optIn": { "$ref": "#/components/schemas/TextOptIn" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "TextOptInRecordInput": { "type": "object", "required": [ "expectedTenantId", "threadId", "channel", "purposes", "evidence" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "threadId": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "sms", "whatsapp" ] }, "purposes": { "type": "array", "items": { "type": "string", "enum": [ "service", "marketing" ] }, "minItems": 0, "maxItems": 2 }, "evidence": { "type": "string", "minLength": 10, "maxLength": 500 } }, "additionalProperties": false }, "TextOptInRevokeInput": { "type": "object", "required": [ "expectedTenantId" ], "properties": { "expectedTenantId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false }, "TextMessageMediaArtifact": { "type": "string", "format": "binary" }, "HolidayImportProposal": { "type": "object", "required": [ "id", "calendarId", "kind", "state", "year", "source", "status", "createdAt", "plan" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "public", "school" ] }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "source": { "type": "string", "enum": [ "vsm-holidays-de-v1", "openholidays-school-v1" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "superseded" ] }, "createdAt": { "type": "string", "format": "date-time" }, "plan": { "$ref": "#/components/schemas/HolidayImportPlan" } }, "additionalProperties": false }, "HolidayImportProposalAcceptInput": { "type": "object", "required": [ "expectedUpdatedAt", "expectedSourceHash" ], "properties": { "locale": { "type": "string", "enum": [ "de", "en" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "expectedSourceHash": { "type": "string", "minLength": 64, "maxLength": 64 } }, "additionalProperties": false }, "HolidayImportProposalDecisionEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "proposal", "result" ], "properties": { "proposal": { "$ref": "#/components/schemas/HolidayImportProposalSummary" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/HolidayImportPlan" }, { "type": "null" } ] } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "HolidayImportProposalDismissInput": { "type": "object", "required": [], "properties": { "locale": { "type": "string", "enum": [ "de", "en" ] } }, "additionalProperties": false }, "HolidayImportProposalListEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HolidayImportProposal" }, "minItems": 0, "maxItems": 20 } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "additionalProperties": false }, "HolidayImportProposalSummary": { "type": "object", "required": [ "id", "calendarId", "kind", "state", "year", "source", "status", "createdAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "public", "school" ] }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "source": { "type": "string", "enum": [ "vsm-holidays-de-v1", "openholidays-school-v1" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed", "superseded" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "TextMessageMediaSendInput": { "type": "object", "required": [ "command", "file" ], "properties": { "command": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "JSON TextMessageSendInput with channel=whatsapp; no template fields. PDF has no body." }, "file": { "type": "string", "format": "binary", "description": "One byte-validated JPEG/PNG <=5,000,000 bytes or PDF <=16,000,000 bytes. No URL input." } }, "additionalProperties": false }, "TenantDeliveryPause": { "type": "object", "additionalProperties": false, "required": [ "mail", "sms", "whatsapp" ], "properties": { "mail": { "type": "boolean" }, "sms": { "type": "boolean" }, "whatsapp": { "type": "boolean" } } }, "OperatorConversationList": { "type": "object", "additionalProperties": false, "required": [ "threads", "truncated", "deliveryPause" ], "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationThread" }, "maxItems": 100 }, "truncated": { "type": "boolean" }, "deliveryPause": { "$ref": "#/components/schemas/TenantDeliveryPause" } } }, "OperatorConversationListEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OperatorConversationList" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "DeliveryProvider": { "type": "string", "enum": [ "smtp", "twilio" ] }, "DeliveryProviderRecoveryInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "commandKey", "reason" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1 }, "commandKey": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "DeliveryProviderRecovery": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "expectedRevision", "status", "failureCode", "requestedAt", "expiresAt", "completedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 191 }, "provider": { "$ref": "#/components/schemas/DeliveryProvider" }, "expectedRevision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "pending", "checking", "succeeded", "failed" ] }, "failureCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 48 }, { "type": "null" } ] }, "requestedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "DeliveryProviderRecoveryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "command", "replayed" ], "properties": { "command": { "$ref": "#/components/schemas/DeliveryProviderRecovery" }, "replayed": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "DeliveryProviderControl": { "type": "object", "additionalProperties": false, "required": [ "provider", "state", "paused", "revision", "reason", "heldAt", "checkedAt", "recovery" ], "properties": { "provider": { "$ref": "#/components/schemas/DeliveryProvider" }, "state": { "type": "string", "enum": [ "active", "held" ] }, "paused": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1 }, "reason": { "anyOf": [ { "type": "string", "enum": [ "SMTP_AUTH_REJECTED", "TWILIO_AUTH_REJECTED" ] }, { "type": "null" } ] }, "heldAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recovery": { "anyOf": [ { "$ref": "#/components/schemas/DeliveryProviderRecovery" }, { "type": "null" } ] } } }, "DeliveryProviderControlSnapshot": { "type": "object", "additionalProperties": false, "required": [ "available", "items" ], "properties": { "available": { "type": "boolean" }, "items": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/DeliveryProviderControl" } } } }, "PublicBookingFormOptions": { "type": "object", "additionalProperties": false, "required": [ "stepOrder" ], "properties": { "stepOrder": { "type": "string", "enum": [ "selection-first", "contact-first" ] }, "intro": { "type": "object", "additionalProperties": false, "required": [], "properties": { "logoUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "contact": { "type": "object", "additionalProperties": false, "required": [ "nameMode", "phoneRequired", "childBooking" ], "properties": { "nameMode": { "type": "string", "enum": [ "single", "split" ] }, "phoneRequired": { "type": "boolean" }, "childBooking": { "type": "boolean" } }, "description": "Contact-step rules. Absent keeps one name field and an optional phone; the public booking command enforces the same rules." }, "confirmation": { "type": "object", "additionalProperties": false, "required": [], "properties": { "preparation": { "type": "boolean", "const": true }, "address": { "type": "boolean", "const": true }, "reviewUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri" }, "share": { "type": "boolean", "const": true } }, "description": "Optional thank-you page blocks; omitted blocks stay hidden." } } }, "PublicBookingCustomerTheme": { "type": "object", "additionalProperties": false, "required": [ "accent", "surface", "text" ], "properties": { "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } } }, "EdgeEmbedSessionRevoked": { "allOf": [ { "$ref": "#/components/schemas/EdgeEmbedSession" }, { "type": "object", "additionalProperties": false, "required": [ "unchanged" ], "properties": { "unchanged": { "type": "boolean" } } } ] }, "EdgeEmbedSessionRevokedEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EdgeEmbedSessionRevoked" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "TenantBranding": { "type": "object", "additionalProperties": false, "required": [ "logoUrl", "colors", "bookingForm" ], "properties": { "logoUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "colors": { "oneOf": [ { "$ref": "#/components/schemas/PublicBookingCustomerTheme" }, { "type": "null" } ] }, "bookingForm": { "oneOf": [ { "$ref": "#/components/schemas/PublicBookingFormOptions" }, { "type": "null" } ] } } }, "TenantBrandingInput": { "type": "object", "additionalProperties": false, "properties": { "logoUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute HTTPS URL without credentials; null clears it." }, { "type": "null" } ] }, "colors": { "oneOf": [ { "$ref": "#/components/schemas/PublicBookingCustomerTheme", "description": "Complete accent/surface/text triple with text contrast >= 4.5; null clears it." }, { "type": "null" } ] }, "bookingForm": { "oneOf": [ { "$ref": "#/components/schemas/PublicBookingFormOptions", "description": "Tenant default form preference; null clears it." }, { "type": "null" } ] } }, "minProperties": 1 }, "TenantBrandingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "branding" ], "properties": { "branding": { "$ref": "#/components/schemas/TenantBranding" } } }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } }, "AdminTenantOwnerInviteInput": { "type": "object", "additionalProperties": false, "required": [ "email", "reason" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "reason": { "type": "string", "minLength": 8, "maxLength": 500 } } }, "AdminTenantOwnerInviteData": { "type": "object", "additionalProperties": false, "required": [ "member", "invite", "replayed", "withdrawnInvites", "auditEventId" ], "properties": { "member": { "$ref": "#/components/schemas/AuthTenantMember" }, "invite": { "anyOf": [ { "$ref": "#/components/schemas/TenantInviteDelivery" }, { "type": "null" } ] }, "replayed": { "type": "boolean" }, "withdrawnInvites": { "type": "integer", "minimum": 0 }, "auditEventId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 191 }, { "type": "null" } ] } } }, "AdminTenantOwnerInviteEnvelope": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AdminTenantOwnerInviteData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } } } }, "securitySchemes": { "apiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "vsm_sk_* API credential", "description": "Tenant-scoped API credential. The operation access metadata names the required scope." }, "operatorSession": { "type": "apiKey", "in": "cookie", "name": "vsm_booking_session", "description": "Authenticated operator browser session." }, "customerSession": { "type": "apiKey", "in": "cookie", "name": "vsm_booking_session", "description": "Verified customer-account browser session." }, "platformAdminSession": { "type": "apiKey", "in": "cookie", "name": "vsm_booking_session", "description": "Authenticated Platform-Admin browser session." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "x-csrf-token", "description": "Required together with a cookie session for unsafe methods; not required for Bearer credentials." }, "oauthMfaChallenge": { "type": "apiKey", "in": "cookie", "name": "vsm_booking_oauth_mfa", "description": "Short-lived HTTP-only challenge cookie issued only after a verified OAuth identity reaches an MFA-enabled account." }, "stripeSignature": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe signature over the exact raw callback body." }, "mailProviderSignature": { "type": "apiKey", "in": "header", "name": "x-vsm-mail-signature", "description": "HMAC SHA-256 provider signature over `.`; timestamps outside 300 seconds are rejected." } } }, "x-vsm-access-contract": "vsm-openapi-access-v1" }