{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "Backstage API", "x-tl-version": "2026-06-13", "description": "API documentation for Backstage platform", "contact": { "name": "API Support", "email": "team@ticketlayer.com" } }, "servers": [ { "url": "https://api.ticketlayer.com/v1", "description": "Production server" } ], "tags": [ { "name": "Authentication", "description": "Authentication and authorization endpoints" }, { "name": "Users", "description": "User management endpoints" }, { "name": "Accounts", "description": "Account management endpoints" }, { "name": "Organisations", "description": "Organisation management endpoints" }, { "name": "Roles", "description": "Role and permission management endpoints" } ], "security": [ { "bearerAuth": [], "orgHeader": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from login endpoint" }, "orgHeader": { "type": "apiKey", "in": "header", "name": "X-Ticketlayer-Org", "description": "Organisation slug to scope the request to a specific organisation" }, "channelKey": { "type": "apiKey", "in": "header", "name": "X-Channel-Key", "description": "Sales channel key (tlpk_ publishable or tlsk_ secret). May also be presented as a Bearer token in the Authorization header. Secret keys must never be used in a browser." } }, "parameters": { "orgHeader": { "name": "X-Ticketlayer-Org", "in": "header", "required": true, "description": "Organisation slug to scope the request", "schema": { "type": "string", "example": "acme-corp" } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": [ "error", "code" ] }, "SuccessResponse": { "type": "object", "properties": { "data": {}, "requestId": { "type": "string" } } }, "GetApiVersionsResponse": { "type": "object", "properties": { "current": { "type": "string", "example": "2026-06-13", "description": "The current dated API version" }, "resolved": { "type": "string", "example": "2026-06-13", "description": "The version this request resolved to (TL-Version header > organisation default > current)" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiVersion" } } }, "required": [ "current", "resolved", "versions" ] }, "ApiVersion": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-06-13", "description": "Dated version identifier (YYYY-MM-DD)" }, "status": { "type": "string", "enum": [ "current", "supported", "deprecated", "sunset" ], "example": "current" }, "summary": { "type": "string", "example": "Baseline dated version." }, "breakingChanges": { "type": "array", "items": { "type": "string" }, "description": "Breaking changes this version introduced vs the previous version" }, "deprecatedAt": { "type": [ "string", "null" ], "example": null }, "sunsetAt": { "type": [ "string", "null" ], "example": null } }, "required": [ "date", "status", "summary", "breakingChanges", "deprecatedAt", "sunsetAt" ] }, "LoginResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "JWT access token" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "JWT refresh token" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "required": [ "id", "email" ] } }, "required": [ "accessToken", "refreshToken", "user" ] }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com", "description": "User email address" }, "password": { "type": "string", "minLength": 1, "example": "password123", "description": "User password" } }, "required": [ "email", "password" ] }, "RefreshTokenResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "New JWT access token" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "New JWT refresh token" } }, "required": [ "accessToken", "refreshToken" ] }, "RefreshTokenRequest": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Refresh token from previous login" } }, "required": [ "refreshToken" ] }, "RedeemInvitationResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "JWT access token" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "JWT refresh token" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "required": [ "id", "email" ] } }, "required": [ "accessToken", "refreshToken", "user" ] }, "RedeemInvitationRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "example": "INV-1234567890", "description": "Invitation code received via email" }, "password": { "type": "string", "minLength": 8, "example": "securePassword123", "description": "New password for the account (minimum 8 characters)" } }, "required": [ "code", "password" ] }, "FederateRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Stagedoor JWT token to federate" } }, "required": [ "token" ] }, "GetMeResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/MeUser" } }, "required": [ "user" ] }, "MeUser": { "type": "object", "properties": { "id": { "type": "string", "example": "usr_abc123" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "identityProvider": { "type": "string", "example": "stagedoor" }, "externalUserId": { "type": "string", "example": "stagedoor-user-123" } }, "required": [ "id", "email" ] }, "GetMeOrganisationsResponse": { "type": "object", "properties": { "organisations": { "type": "array", "items": { "$ref": "#/components/schemas/MeOrganisation" } } }, "required": [ "organisations" ] }, "MeOrganisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_xyz789" }, "slug": { "type": "string", "example": "acme-corp" }, "name": { "type": "string", "example": "Acme Corporation" }, "primaryColor": { "type": "string", "example": "#FF5733" }, "secondaryColor": { "type": "string", "example": "#3366FF" }, "logoUrl": { "type": "string", "example": "https://example.com/logo.png" }, "userId": { "type": "string", "example": "usr_abc123", "description": "The user ID in this specific organisation" } }, "required": [ "id", "slug", "name", "userId" ] }, "GetMeRolesResponse": { "type": "object", "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/MeRoleAssignment" } }, "isOrgAdmin": { "type": "boolean", "example": true, "description": "Whether the user has org-wide admin access" } }, "required": [ "roles", "isOrgAdmin" ] }, "MeRoleAssignment": { "type": "object", "properties": { "id": { "type": "string", "example": "rol_system_org_owner" }, "name": { "type": [ "string", "null" ], "example": "Organisation Owner" }, "description": { "type": [ "string", "null" ], "example": "Full administrative access to the organisation" }, "accountId": { "type": "string", "example": "acc_abc123" }, "isSystemRole": { "type": "boolean", "example": true } }, "required": [ "id", "name", "description", "accountId", "isSystemRole" ] }, "GetMePermissionsResponse": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/MePermissionEntry" } }, "isOrgAdmin": { "type": "boolean", "example": true }, "filters": { "type": "object", "properties": { "resource": { "type": [ "string", "null" ], "example": "events" }, "action": { "type": [ "string", "null" ], "example": "create" } }, "required": [ "resource", "action" ] } }, "required": [ "permissions", "isOrgAdmin", "filters" ] }, "MePermissionEntry": { "type": "object", "properties": { "permission": { "type": "string", "example": "events.create" }, "accounts": { "type": "array", "items": { "type": "string" }, "example": [ "all" ], "description": "Account IDs this permission applies to, or [\"all\"] for org-wide" }, "isAllAccounts": { "type": "boolean", "example": true } }, "required": [ "permission", "accounts", "isAllAccounts" ] }, "GetOrganisationResponse": { "type": "object", "properties": { "organisation": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "organisation" ] }, "Organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Acme Corporation" }, "primaryColor": { "type": "string", "example": "#FF5733" }, "secondaryColor": { "type": "string", "example": "#3366FF" }, "logoUrl": { "type": "string", "example": "https://example.com/logo.png" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "industry": "Technology", "size": "Medium" } }, "apiVersion": { "type": "string", "example": "2026-06-13", "description": "The dated API version this organisation is pinned to (see GET /meta/versions)" }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" } }, "required": [ "id", "name", "apiVersion", "createdAt", "updatedAt" ] }, "UpdateOrganisationResponse": { "type": "object", "properties": { "organisation": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "organisation" ] }, "UpdateOrganisationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Acme Corporation", "description": "Organisation name" }, "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#FF5733", "description": "Primary brand color (hex format)" }, "secondaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#3366FF", "description": "Secondary brand color (hex format)" }, "logoUrl": { "type": "string", "format": "uri", "example": "https://example.com/logo.png", "description": "URL to organisation logo" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "industry": "Technology", "size": "Medium" }, "description": "Additional metadata" }, "apiVersion": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-06-13", "description": "Pin the organisation to a dated API version. Must be a known, non-sunset version (see GET /meta/versions)." } } }, "ListAccountsResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } }, "required": [ "accounts" ] }, "Account": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Main Account" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" } }, "required": [ "id", "organisationId", "name", "status", "isDeleted", "createdAt", "updatedAt" ] }, "GetAccountResponse": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": [ "account" ] }, "CreateAccountResponse": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": [ "account" ] }, "UpdateAccountResponse": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": [ "account" ] }, "DeleteAccountResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "acc_abc123" } }, "required": [ "success", "id" ] }, "ListIdentityProvidersResponse": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProvider" } } }, "required": [ "providers" ] }, "IdentityProvider": { "type": "object", "properties": { "id": { "type": "string", "example": "stagedoor-idp" }, "organisationId": { "type": [ "string", "null" ], "example": "org_abc123" }, "providerType": { "type": "string", "example": "stagedoor" }, "isDefault": { "type": "boolean", "example": true }, "isEnabled": { "type": "boolean", "example": true }, "issuer": { "type": "string", "example": "https://stagedoor.example.com" }, "authorizationEndpoint": { "type": [ "string", "null" ], "example": "https://stagedoor.example.com/api/oauth/authorize" }, "tokenEndpoint": { "type": [ "string", "null" ], "example": "https://stagedoor.example.com/api/oauth/token" }, "tokenEndpointInternal": { "type": [ "string", "null" ], "example": "http://stagedoor:3000/api/oauth/token" }, "userinfoEndpoint": { "type": [ "string", "null" ], "example": "https://stagedoor.example.com/api/oauth/userinfo" }, "userinfoEndpointInternal": { "type": [ "string", "null" ], "example": "http://stagedoor:3000/api/oauth/userinfo" }, "jwksUri": { "type": "string", "example": "https://stagedoor.example.com/.well-known/jwks.json" }, "jwksUriInternal": { "type": [ "string", "null" ], "example": "http://stagedoor:3000/.well-known/jwks.json" }, "clientId": { "type": [ "string", "null" ], "example": "backstage-app" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "profile", "email" ] }, "allowedClientIds": { "type": "array", "items": { "type": "string" }, "example": [ "backstage-app", "backstage-boxoffice" ] }, "emailDomain": { "type": [ "string", "null" ], "example": "@example.com" }, "supportsPkce": { "type": "boolean", "example": true }, "cacheTtl": { "type": "number", "example": 300 }, "configuration": { "type": [ "object", "null" ], "additionalProperties": {}, "example": {} }, "createdAt": { "type": "string", "example": "2024-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2024-01-01T00:00:00.000Z" } }, "required": [ "id", "organisationId", "providerType", "isDefault", "isEnabled", "issuer", "authorizationEndpoint", "tokenEndpoint", "tokenEndpointInternal", "userinfoEndpoint", "userinfoEndpointInternal", "jwksUri", "jwksUriInternal", "clientId", "scopes", "allowedClientIds", "emailDomain", "supportsPkce", "cacheTtl", "configuration", "createdAt", "updatedAt" ] }, "GetIdentityProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/IdentityProvider" } }, "required": [ "provider" ] }, "UpdateIdentityProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/IdentityProvider" } }, "required": [ "provider" ] }, "UpdateIdentityProviderRequest": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "example": true }, "isDefault": { "type": "boolean", "example": false }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "openid", "profile", "email" ] }, "allowedClientIds": { "type": "array", "items": { "type": "string" }, "example": [ "backstage-app" ] }, "emailDomain": { "type": [ "string", "null" ], "example": "@example.com" }, "cacheTtl": { "type": "number", "example": 600 }, "configuration": { "type": "object", "additionalProperties": {}, "example": {} } } }, "CreateUserInvitationResponse": { "type": "object", "properties": { "invitation": { "$ref": "#/components/schemas/UserInvitation" } }, "required": [ "invitation" ] }, "UserInvitation": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "userId": { "type": "string", "example": "usr_pending123" }, "code": { "type": "string", "example": "inv_BvQ8mK..." }, "email": { "type": "string", "format": "email", "example": "newuser@example.com" }, "expiresAt": { "type": "string", "example": "2024-01-08T00:00:00.000Z" }, "redeemedAt": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2024-01-01T00:00:00.000Z" } }, "required": [ "id", "organisationId", "userId", "code", "email", "expiresAt", "redeemedAt", "createdAt" ] }, "CreateUserInvitationRequest": { "type": "object", "properties": { "organisationId": { "type": "string", "example": "org_xyz789" }, "email": { "type": "string", "format": "email", "example": "newuser@example.com" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "roleIds": { "type": "array", "items": { "type": "string" }, "example": [ "rol_admin123" ] } }, "required": [ "organisationId", "email" ] }, "ListUserInvitationsResponse": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvitation" } } }, "required": [ "invitations" ] }, "GetUserInvitationResponse": { "type": "object", "properties": { "invitation": { "$ref": "#/components/schemas/UserInvitation" } }, "required": [ "invitation" ] }, "DeleteUserInvitationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "inv_abc123" } }, "required": [ "success", "id" ] }, "ResendUserInvitationResponse": { "type": "object", "properties": { "invitation": { "$ref": "#/components/schemas/UserInvitation" } }, "required": [ "invitation" ] }, "ListRolesResponse": { "type": "object", "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } }, "required": [ "roles" ] }, "Role": { "type": "object", "properties": { "id": { "type": "string", "example": "rol_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Event Manager" }, "description": { "type": [ "string", "null" ], "example": "Manages events and related resources" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings in format resource.action:scope" }, "isSystemRole": { "type": "boolean", "example": false, "description": "Whether this is a system-defined role (cannot be modified or deleted)" } }, "required": [ "id", "organisationId", "name", "description", "isDeleted", "createdAt", "updatedAt", "permissions", "isSystemRole" ] }, "GetRoleResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "rol_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Event Manager" }, "description": { "type": [ "string", "null" ], "example": "Manages events and related resources" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings in format resource.action:scope" }, "isSystemRole": { "type": "boolean", "example": false, "description": "Whether this is a system-defined role (cannot be modified or deleted)" } }, "required": [ "id", "organisationId", "name", "description", "isDeleted", "createdAt", "updatedAt", "permissions", "isSystemRole" ] }, "CreateRoleResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "rol_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Event Manager" }, "description": { "type": [ "string", "null" ], "example": "Manages events and related resources" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings in format resource.action:scope" }, "isSystemRole": { "type": "boolean", "example": false, "description": "Whether this is a system-defined role (cannot be modified or deleted)" } }, "required": [ "id", "organisationId", "name", "description", "isDeleted", "createdAt", "updatedAt", "permissions", "isSystemRole" ] }, "CreateRoleRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Event Manager", "description": "The name of the role" }, "description": { "type": "string", "maxLength": 500, "example": "Manages events and related resources", "description": "Optional description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(\\*|\\w+)\\.(\\*|\\w+)(:(all|acc_[a-zA-Z0-9]+))?$", "example": "events.create", "description": "Permission in format resource.action:scope. Scope is optional (dynamic if omitted)." }, "minItems": 1, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings" } }, "required": [ "name", "permissions" ] }, "UpdateRoleResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "rol_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Event Manager" }, "description": { "type": [ "string", "null" ], "example": "Manages events and related resources" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings in format resource.action:scope" }, "isSystemRole": { "type": "boolean", "example": false, "description": "Whether this is a system-defined role (cannot be modified or deleted)" } }, "required": [ "id", "organisationId", "name", "description", "isDeleted", "createdAt", "updatedAt", "permissions", "isSystemRole" ] }, "UpdateRoleRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Event Manager", "description": "The name of the role" }, "description": { "type": "string", "maxLength": 500, "example": "Manages events and related resources", "description": "Optional description of the role" }, "permissions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(\\*|\\w+)\\.(\\*|\\w+)(:(all|acc_[a-zA-Z0-9]+))?$", "example": "events.create", "description": "Permission in format resource.action:scope. Scope is optional (dynamic if omitted)." }, "minItems": 1, "example": [ "events.*", "venues.read:all", "orders.read" ], "description": "Array of permission strings" } } }, "DeleteRoleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "rol_abc123" } }, "required": [ "success", "id" ] }, "ListUserAccountRolesResponse": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/UserAccountRoleAssignment" } } }, "required": [ "assignments" ] }, "UserAccountRoleAssignment": { "type": "object", "properties": { "id": { "type": "string", "example": "uar_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "userId": { "type": "string", "example": "usr_abc123" }, "accountId": { "type": "string", "example": "acc_xyz789" }, "roleId": { "type": "string", "example": "rol_system_event_manager" }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "firstName", "lastName" ], "description": "User details" }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "Account details" }, "role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isSystemRole": { "type": "boolean" } }, "required": [ "id", "name", "isSystemRole" ], "description": "Role details" } }, "required": [ "id", "organisationId", "userId", "accountId", "roleId", "createdAt" ] }, "AssignRoleResponse": { "type": "object", "properties": { "assignment": { "$ref": "#/components/schemas/UserAccountRoleAssignment" } }, "required": [ "assignment" ] }, "AssignRoleRequest": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^usr_[a-zA-Z0-9]+$", "example": "usr_abc123", "description": "User ID" }, "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_abc123", "description": "Account ID" }, "roleId": { "type": "string", "pattern": "^rol_[a-zA-Z0-9_]+$", "example": "rol_system_event_manager", "description": "Role ID (can be a system role or custom role)" } }, "required": [ "userId", "accountId", "roleId" ] }, "UpdateUserAccountRolesResponse": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/UserAccountRoleAssignment" } } }, "required": [ "assignments" ] }, "UpdateUserAccountRolesRequest": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^usr_[a-zA-Z0-9]+$", "example": "usr_abc123", "description": "User ID" }, "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_abc123", "description": "Account ID" }, "roleIds": { "type": "array", "items": { "type": "string", "pattern": "^rol_[a-zA-Z0-9_]+$" }, "example": [ "rol_system_event_manager", "rol_system_box_office" ], "description": "Array of role IDs to assign (replaces existing roles)" } }, "required": [ "userId", "accountId", "roleIds" ] }, "RemoveAssignmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "PartnerAccountProvisioned": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Leander Rowing Club" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2026-09-12T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-09-12T10:30:00Z" } }, "required": [ "id", "organisationId", "name", "status", "isDeleted", "createdAt", "updatedAt" ] }, "salesChannel": { "type": "object", "properties": { "id": { "type": "string", "example": "sch_abc123" }, "slug": { "type": "string", "example": "leander-rowing-club-k7x2pq" }, "channelType": { "type": "string", "example": "website" } }, "required": [ "id", "slug", "channelType" ] }, "publishableKey": { "type": "object", "properties": { "id": { "type": "string", "example": "schk_abc123" }, "key": { "type": "string", "example": "tlpk_...", "description": "Publishable key material - returned once, at creation" } }, "required": [ "id", "key" ] } }, "required": [ "account", "salesChannel", "publishableKey" ] }, "OrgApiKeyCreated": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/OrgApiKey" }, "key": { "type": "string", "example": "tlak_...", "description": "The key material - returned once, at creation, and never retrievable again" } }, "required": [ "apiKey", "key" ] }, "OrgApiKey": { "type": "object", "properties": { "id": { "type": "string", "example": "oak_abc12345" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": [ "string", "null" ], "example": null, "description": "Account the key is pinned to; null means every account in the organisation" }, "name": { "type": "string", "example": "Rowbot production" }, "keyPrefix": { "type": "string", "example": "tlak_AbCdEfG", "description": "First 12 characters of the key, for display" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "accounts.write", "events.read" ] }, "createdBy": { "type": [ "string", "null" ], "example": "usr_abc123" }, "createdAt": { "type": "string", "example": "2026-09-12T10:30:00Z" }, "lastUsedAt": { "type": [ "string", "null" ], "example": "2026-09-12T11:00:00Z" }, "expiresAt": { "type": [ "string", "null" ], "example": null }, "revokedAt": { "type": [ "string", "null" ], "example": null } }, "required": [ "id", "organisationId", "accountId", "name", "keyPrefix", "scopes", "createdBy", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ] }, "ListOrgApiKeysResponse": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/OrgApiKey" } } }, "required": [ "apiKeys" ] }, "OrgApiKeyRevoked": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/OrgApiKey" } }, "required": [ "apiKey" ] }, "EmbedSessionCreated": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiJ9...", "description": "Embed session JWT; the widget sends it as Authorization: Bearer" }, "expiresAt": { "type": "string", "example": "2026-09-12T10:45:00Z" }, "accountId": { "type": "string", "example": "acc_abc123" }, "organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_xyz789" }, "slug": { "type": "string", "example": "rowbot", "description": "Value for the X-Ticketlayer-Org header" } }, "required": [ "id", "slug" ] } }, "required": [ "token", "expiresAt", "accountId", "organisation" ] }, "CurrentEmbedSession": { "type": "object", "properties": { "organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_xyz789" }, "slug": { "type": "string", "example": "rowbot", "description": "Value for the X-Ticketlayer-Org header" } }, "required": [ "id", "slug" ] }, "accountId": { "type": "string", "example": "acc_abc123" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "events.read", "orders.read" ] }, "expiresAt": { "type": "string", "example": "2026-09-12T10:45:00Z" } }, "required": [ "organisation", "accountId", "scopes", "expiresAt" ] }, "ListEventsResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "events", "pagination" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "name": { "type": "string", "example": "Summer Music Festival" }, "description": { "type": "string", "example": "A three-day music festival" }, "status": { "type": "string", "enum": [ "draft", "published", "on_sale", "sold_out", "completed", "cancelled" ], "example": "draft" }, "venueId": { "type": "string", "example": "vnu_ghi789" }, "timezone": { "type": "string", "example": "Europe/London" }, "onSaleDate": { "type": "string", "example": "2025-06-01T09:00:00Z" }, "offSaleDate": { "type": "string", "example": "2025-06-15T23:59:59Z" }, "occurrenceCount": { "type": "number", "example": 3 }, "ticketCount": { "type": "number", "example": 0 }, "productCount": { "type": "number", "example": 0 }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "music", "festival" ] }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" }, "createdBy": { "type": "string", "example": "usr_abc123" } }, "required": [ "id", "organisationId", "accountId", "name", "status", "timezone", "occurrenceCount", "ticketCount", "productCount", "tags", "isDeleted", "createdAt", "updatedAt" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 20 }, "total": { "type": "number", "example": 45 }, "totalPages": { "type": "number", "example": 3 }, "hasNext": { "type": "boolean", "example": true }, "hasPrev": { "type": "boolean", "example": false } }, "required": [ "page", "limit", "total", "totalPages", "hasNext", "hasPrev" ] }, "GetEventResponse": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" } }, "required": [ "event" ] }, "CreateEventResponse": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" } }, "required": [ "event" ] }, "UpdateEventResponse": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" } }, "required": [ "event" ] }, "DeleteEventResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "evt_abc123" } }, "required": [ "success", "id" ] }, "ListEventOccurrencesResponse": { "type": "object", "properties": { "eventOccurrences": { "type": "array", "items": { "$ref": "#/components/schemas/EventOccurrence" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "eventOccurrences", "pagination" ] }, "EventOccurrence": { "type": "object", "properties": { "id": { "type": "string", "example": "eoc_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "eventId": { "type": "string", "example": "evt_ghi789" }, "startDate": { "type": "string", "example": "2025-06-15T00:00:00Z" }, "startTime": { "type": "string", "example": "19:00:00" }, "endDate": { "type": "string", "example": "2025-06-15T00:00:00Z" }, "endTime": { "type": "string", "example": "23:00:00" }, "timezone": { "type": "string", "example": "Europe/London" }, "venueId": { "type": "string", "example": "vnu_abc123" }, "status": { "type": "string", "enum": [ "draft", "on_sale", "sold_out", "completed", "cancelled" ], "example": "draft" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" } }, "required": [ "id", "organisationId", "accountId", "eventId", "startDate", "startTime", "endDate", "endTime", "timezone", "status", "isDeleted", "createdAt", "updatedAt" ] }, "GetEventOccurrenceResponse": { "type": "object", "properties": { "eventOccurrence": { "$ref": "#/components/schemas/EventOccurrence" } }, "required": [ "eventOccurrence" ] }, "CreateEventOccurrenceResponse": { "type": "object", "properties": { "eventOccurrence": { "$ref": "#/components/schemas/EventOccurrence" } }, "required": [ "eventOccurrence" ] }, "UpdateEventOccurrenceResponse": { "type": "object", "properties": { "eventOccurrence": { "$ref": "#/components/schemas/EventOccurrence" } }, "required": [ "eventOccurrence" ] }, "DeleteEventOccurrenceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "evoc_abc123" } }, "required": [ "success", "id" ] }, "ListPriceSchemesResponse": { "type": "object", "properties": { "priceSchemes": { "type": "array", "items": { "$ref": "#/components/schemas/PriceScheme" } } }, "required": [ "priceSchemes" ] }, "PriceScheme": { "type": "object", "properties": { "id": { "type": "string", "example": "tps_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "eventId": { "type": "string", "example": "evt_ghi789" }, "name": { "type": "string", "example": "Standard Pricing" }, "description": { "type": "string", "example": "Default pricing for all shows" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "example": "active" }, "parentPriceSchemeId": { "type": "string", "example": "tps_parent123" }, "ticketPrices": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPrice" }, "description": "Price matrix entries" }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" } }, "required": [ "id", "organisationId", "accountId", "eventId", "name", "status", "ticketPrices", "isDeleted", "createdAt", "updatedAt" ] }, "TicketPrice": { "type": "object", "properties": { "categoryId": { "type": "string", "example": "cat_abc123" }, "typeId": { "type": "string", "example": "tt_def456" }, "price": { "type": "number", "example": 2500, "description": "Price in smallest unit (pence/cents)" }, "currency": { "type": "string", "enum": [ "GBP", "USD", "EUR", "AUD", "CAD" ], "example": "GBP" } }, "required": [ "categoryId", "typeId", "price", "currency" ] }, "CreatePriceSchemeResponse": { "type": "object", "properties": { "priceScheme": { "$ref": "#/components/schemas/PriceScheme" } }, "required": [ "priceScheme" ] }, "GetPriceSchemeResponse": { "type": "object", "properties": { "priceScheme": { "$ref": "#/components/schemas/PriceScheme" } }, "required": [ "priceScheme" ] }, "UpdatePriceSchemeResponse": { "type": "object", "properties": { "priceScheme": { "$ref": "#/components/schemas/PriceScheme" } }, "required": [ "priceScheme" ] }, "DeletePriceSchemeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "tps_abc123" } }, "required": [ "success", "id" ] }, "ListVenuesResponse": { "type": "object", "properties": { "venues": { "type": "array", "items": { "$ref": "#/components/schemas/Venue" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "venues", "pagination" ] }, "Venue": { "type": "object", "properties": { "id": { "type": "string", "example": "vnu_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "name": { "type": "string", "example": "Royal Albert Hall" }, "description": { "type": "string", "example": "Historic concert hall in London" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active" }, "streetAddress": { "type": "string", "example": "Kensington Gore" }, "country": { "type": "string", "example": "United Kingdom" }, "coordinates": { "$ref": "#/components/schemas/GeoJSONPoint" }, "timezone": { "type": "string", "example": "Europe/London" }, "phone": { "type": "string", "example": "+44 20 7589 8212" }, "email": { "type": "string", "example": "info@royalalberthall.com" }, "website": { "type": "string", "example": "https://www.royalalberthall.com" }, "features": { "type": "array", "items": { "type": "string" }, "example": [ "parking", "wheelchair_accessible", "bar" ] }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "concert-hall", "historic" ] }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" }, "createdBy": { "type": "string", "example": "usr_abc123" } }, "required": [ "id", "organisationId", "accountId", "name", "status", "timezone", "features", "tags", "isDeleted", "createdAt", "updatedAt" ] }, "GeoJSONPoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Point" ], "example": "Point" }, "coordinates": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "example": [ -0.1278, 51.5074 ] } }, "required": [ "type", "coordinates" ] }, "GetVenueResponse": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" } }, "required": [ "venue" ] }, "CreateVenueResponse": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" } }, "required": [ "venue" ] }, "UpdateVenueResponse": { "type": "object", "properties": { "venue": { "$ref": "#/components/schemas/Venue" } }, "required": [ "venue" ] }, "DeleteVenueResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "vnu_abc123" } }, "required": [ "success", "id" ] }, "ListVenueLayoutsResponse": { "type": "object", "properties": { "venueLayouts": { "type": "array", "items": { "$ref": "#/components/schemas/VenueLayout" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "venueLayouts", "pagination" ] }, "VenueLayout": { "type": "object", "properties": { "id": { "type": "string", "example": "vlt_abc123" }, "venueId": { "type": "string", "example": "vnu_def456" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_ghi012" }, "name": { "type": "string", "example": "Theatre Mode" }, "description": { "type": "string", "example": "Standard theatre configuration" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active" }, "totalCapacity": { "type": "number", "example": 1500 }, "categories": { "type": "array", "items": {}, "example": [] }, "areas": { "type": "array", "items": {}, "example": [] }, "decorations": { "type": "array", "items": { "$ref": "#/components/schemas/Decoration" }, "example": [] }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "theatre", "seated" ] }, "isDeleted": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" }, "createdBy": { "type": "string", "example": "usr_abc123" } }, "required": [ "id", "venueId", "organisationId", "accountId", "name", "status", "totalCapacity", "categories", "areas", "tags", "isDeleted", "createdAt", "updatedAt" ] }, "Decoration": { "type": "object", "properties": { "id": { "type": "string", "example": "vld_abc123" }, "type": { "type": "string", "enum": [ "stage", "pillar", "barrier", "aisle", "wall", "exit", "entrance", "bar", "restroom", "label", "custom" ], "example": "stage" }, "name": { "type": "string", "example": "Main Stage" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100 }, "y": { "type": "number", "example": 50 }, "width": { "type": "number", "example": 300 }, "height": { "type": "number", "example": 80 }, "rotation": { "type": "number", "example": 0 } }, "required": [ "x", "y", "width", "height" ] }, "label": { "type": "string", "example": "STAGE" }, "style": { "type": "object", "properties": { "fill": { "type": "string", "example": "#1f2937" }, "stroke": { "type": "string", "example": "#111827" }, "fontSize": { "type": "number", "example": 14 }, "fontWeight": { "type": "string", "example": "bold" } } } }, "required": [ "id", "type", "position" ] }, "GetVenueLayoutResponse": { "type": "object", "properties": { "venueLayout": { "$ref": "#/components/schemas/VenueLayout" } }, "required": [ "venueLayout" ] }, "CreateVenueLayoutResponse": { "type": "object", "properties": { "venueLayout": { "$ref": "#/components/schemas/VenueLayout" } }, "required": [ "venueLayout" ] }, "UpdateVenueLayoutResponse": { "type": "object", "properties": { "venueLayout": { "$ref": "#/components/schemas/VenueLayout" } }, "required": [ "venueLayout" ] }, "DeleteVenueLayoutResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "vnl_abc123" } }, "required": [ "success", "id" ] }, "AddAreaResponse": { "type": "object", "properties": { "venueLayout": {}, "area": { "$ref": "#/components/schemas/VenueLayoutArea" } }, "required": [ "area" ] }, "VenueLayoutArea": { "type": "object", "properties": { "id": { "type": "string", "example": "vla_abc123" }, "name": { "type": "string", "example": "Main Floor" }, "description": { "type": "string", "example": "General admission area" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "capacity": { "type": "number", "example": 500 }, "displayOrder": { "type": "number", "example": 1 }, "color": { "type": "string", "example": "#FFD700" }, "seats": { "type": "array", "items": {}, "example": [] } }, "required": [ "id", "name", "type", "status", "capacity", "displayOrder" ] }, "UpdateAreaResponse": { "type": "object", "properties": { "venueLayout": {}, "area": { "$ref": "#/components/schemas/VenueLayoutArea" } }, "required": [ "area" ] }, "DeleteAreaResponse": { "type": "object", "properties": { "venueLayout": {}, "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "AddCategoryResponse": { "type": "object", "properties": { "venueLayout": {}, "category": { "$ref": "#/components/schemas/VenueLayoutCategory" } }, "required": [ "category" ] }, "VenueLayoutCategory": { "type": "object", "properties": { "id": { "type": "string", "example": "vlc_abc123" }, "name": { "type": "string", "example": "Premium" }, "description": { "type": "string", "example": "Best seats in the house" }, "displayOrder": { "type": "number", "example": 1 }, "color": { "type": "string", "example": "#FFD700" } }, "required": [ "id", "name", "displayOrder" ] }, "UpdateCategoryResponse": { "type": "object", "properties": { "venueLayout": {}, "category": { "$ref": "#/components/schemas/VenueLayoutCategory" } }, "required": [ "category" ] }, "DeleteCategoryResponse": { "type": "object", "properties": { "venueLayout": {}, "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "AddSeatResponse": { "type": "object", "properties": { "venueLayout": {}, "seat": { "$ref": "#/components/schemas/VenueLayoutSeat" } }, "required": [ "seat" ] }, "VenueLayoutSeat": { "type": "object", "properties": { "id": { "type": "string", "example": "vlas_abc123" }, "section": { "type": "string", "example": "Orchestra Center" }, "row": { "type": "string", "example": "A" }, "number": { "type": "string", "example": "15" }, "label": { "type": "string", "example": "Orchestra Center, Row A, Seat 15" }, "categoryId": { "type": "string", "example": "vlc_premium" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "example": "available" }, "holdType": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "companionSeats": { "type": "array", "items": { "type": "string" } }, "companionTo": { "type": "string" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "rotation": { "type": "number" } }, "required": [ "x", "y" ] }, "internalNotes": { "type": "string" }, "publicNotes": { "type": "string" } }, "required": [ "id", "row", "number", "label", "status" ] }, "BulkAddSeatsResponse": { "type": "object", "properties": { "venueLayout": {}, "seatsAdded": { "type": "number", "example": 50 } }, "required": [ "seatsAdded" ] }, "GenerateSeatsResponse": { "type": "object", "properties": { "venueLayout": {}, "seatsGenerated": { "type": "number", "example": 200 }, "seats": { "type": "array", "items": { "$ref": "#/components/schemas/VenueLayoutSeat" } } }, "required": [ "seatsGenerated", "seats" ] }, "SyncSeatsResponse": { "type": "object", "properties": { "venueLayout": {}, "seatsSynced": { "type": "number", "example": 150 }, "seats": { "type": "array", "items": { "$ref": "#/components/schemas/VenueLayoutSeat" } } }, "required": [ "seatsSynced", "seats" ] }, "UpdateSeatResponse": { "type": "object", "properties": { "venueLayout": {}, "seat": { "$ref": "#/components/schemas/VenueLayoutSeat" } }, "required": [ "seat" ] }, "DeleteSeatResponse": { "type": "object", "properties": { "venueLayout": {}, "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "ListPackagesResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPackage" } } }, "required": [ "packages" ] }, "CreditPackage": { "type": "object", "properties": { "id": { "type": "string", "example": "pkg_100" }, "name": { "type": "string", "example": "100 Credits" }, "credits": { "type": "number", "example": 100 }, "basePrice": { "type": "integer", "example": 2500, "description": "Integer minor units (e.g. 2500 = $25.00)" }, "baseCurrency": { "type": "string", "example": "USD" }, "discountPercent": { "type": "string", "example": "0.00", "description": "Percent rate" }, "finalPrice": { "type": "integer", "example": 2500, "description": "Integer minor units" }, "isActive": { "type": "boolean", "example": true }, "displayOrder": { "type": "number", "example": 1 } }, "required": [ "id", "name", "credits", "basePrice", "baseCurrency", "discountPercent", "finalPrice", "isActive", "displayOrder" ] }, "CanSellResponse": { "type": "object", "properties": { "canSell": { "type": "boolean", "example": true }, "reason": { "type": [ "string", "null" ], "example": null }, "currentBalance": { "type": "number", "example": 150 } }, "required": [ "canSell", "reason", "currentBalance" ] }, "GetBalanceResponse": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/CreditBalance" } }, "required": [ "balance" ] }, "CreditBalance": { "type": "object", "properties": { "id": { "type": "string", "example": "bal_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "balance": { "type": "number", "example": 150 }, "lifetimeCredits": { "type": "number", "example": 500 }, "lifetimeUsed": { "type": "number", "example": 350 }, "isSuspended": { "type": "boolean", "example": false }, "suspendedAt": { "type": [ "string", "null" ], "example": null }, "suspendedReason": { "type": [ "string", "null" ], "example": null }, "status": { "type": "string", "enum": [ "healthy", "low", "depleted", "negative", "suspended" ], "example": "healthy" }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" } }, "required": [ "id", "organisationId", "balance", "lifetimeCredits", "lifetimeUsed", "isSuspended", "suspendedAt", "suspendedReason", "status", "createdAt", "updatedAt" ] }, "ListTransactionsResponse": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTransaction" } } }, "required": [ "transactions" ] }, "CreditTransaction": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "type": { "type": "string", "enum": [ "initial", "purchase", "subscription", "ticket_sale", "adjustment", "refund" ], "example": "purchase" }, "amount": { "type": "number", "example": 100 }, "balanceBefore": { "type": "number", "example": 50 }, "balanceAfter": { "type": "number", "example": 150 }, "orderId": { "type": [ "string", "null" ], "example": null }, "invoiceId": { "type": [ "string", "null" ], "example": "inv_abc123" }, "subscriptionId": { "type": [ "string", "null" ], "example": null }, "description": { "type": [ "string", "null" ], "example": "Credit purchase - 100 Credits" }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "type", "amount", "balanceBefore", "balanceAfter", "orderId", "invoiceId", "subscriptionId", "description", "createdAt" ] }, "PurchaseResult": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "payment": { "$ref": "#/components/schemas/Payment" }, "transaction": { "$ref": "#/components/schemas/CreditTransaction" }, "newBalance": { "type": "number", "example": 150 } }, "required": [ "success", "invoice", "payment", "transaction", "newBalance" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "invoiceNumber": { "type": "string", "example": "INV-2024-0001" }, "type": { "type": "string", "enum": [ "purchase", "subscription", "payg" ], "example": "purchase" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ], "example": "paid" }, "subtotal": { "type": "integer", "example": 2500 }, "tax": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 2500 }, "amountPaid": { "type": "integer", "example": 2500 }, "amountDue": { "type": "integer", "example": 0 }, "currency": { "type": "string", "example": "USD" }, "issueDate": { "type": "string", "example": "2024-01-15" }, "dueDate": { "type": [ "string", "null" ], "example": "2024-01-30" }, "paidAt": { "type": [ "string", "null" ], "example": "2024-01-15T10:35:00Z" }, "pdfUrl": { "type": [ "string", "null" ], "example": "https://invoice.stripe.com/..." }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:35:00Z" } }, "required": [ "id", "organisationId", "invoiceNumber", "type", "status", "subtotal", "tax", "total", "amountPaid", "amountDue", "currency", "issueDate", "dueDate", "paidAt", "pdfUrl", "createdAt", "updatedAt" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "example": "pay_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "invoiceId": { "type": [ "string", "null" ], "example": "inv_abc123" }, "amount": { "type": "integer", "example": 2500, "description": "Integer minor units (e.g. 2500 = $25.00)" }, "currency": { "type": "string", "example": "USD" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "cancelled", "refunded" ], "example": "succeeded" }, "method": { "type": [ "string", "null" ], "example": "card" }, "paidAt": { "type": [ "string", "null" ], "example": "2024-01-15T10:35:00Z" }, "failedAt": { "type": [ "string", "null" ], "example": null }, "failureCode": { "type": [ "string", "null" ], "example": null }, "failureMessage": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:35:00Z" } }, "required": [ "id", "organisationId", "invoiceId", "amount", "currency", "status", "method", "paidAt", "failedAt", "failureCode", "failureMessage", "createdAt", "updatedAt" ] }, "CreatePurchaseRequest": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "paymentMethodId": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "email": { "type": "string", "format": "email" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddress" } }, "required": [ "packageId", "paymentMethodId" ] }, "BillingAddress": { "type": "object", "properties": { "name": { "type": "string" }, "line1": { "type": "string", "minLength": 1 }, "line2": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "state": { "type": "string" }, "postal_code": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "line1", "city", "postal_code", "country" ] }, "ListInvoicesResponse": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }, "required": [ "invoices" ] }, "GetInvoiceResponse": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } }, "required": [ "invoice" ] }, "ListPaymentsResponse": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "payments" ] }, "CreateSubscriptionResponse": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } }, "required": [ "subscription" ] }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "packageId": { "type": "string", "example": "pkg_100" }, "status": { "type": "string", "enum": [ "active", "cancelled", "paused", "past_due", "ended" ], "example": "active" }, "credits": { "type": "number", "example": 100 }, "price": { "type": "integer", "example": 2500, "description": "Integer minor units" }, "currency": { "type": "string", "example": "USD" }, "interval": { "type": "string", "enum": [ "month", "year" ], "example": "month" }, "currentPeriodStart": { "type": [ "string", "null" ], "example": "2024-01-15T00:00:00Z" }, "currentPeriodEnd": { "type": [ "string", "null" ], "example": "2024-02-15T00:00:00Z" }, "cancelledAt": { "type": [ "string", "null" ], "example": null }, "endedAt": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "packageId", "status", "credits", "price", "currency", "interval", "currentPeriodStart", "currentPeriodEnd", "cancelledAt", "endedAt", "createdAt", "updatedAt" ] }, "CreateSubscriptionRequest": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "paymentMethodId": { "type": "string", "minLength": 1 }, "interval": { "type": "string", "enum": [ "month", "year" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "email": { "type": "string", "format": "email" } }, "required": [ "packageId", "paymentMethodId", "interval" ] }, "ListSubscriptionsResponse": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } }, "required": [ "subscriptions" ] }, "CancelSubscriptionResponse": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } }, "required": [ "subscription" ] }, "GetAutoTopupResponse": { "type": "object", "properties": { "autoTopup": { "$ref": "#/components/schemas/AutoTopupConfig" } }, "required": [ "autoTopup" ] }, "AutoTopupConfig": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "atu_abc123" }, "organisationId": { "type": "string", "example": "org_abc123" }, "enabled": { "type": "boolean", "example": true }, "thresholdCredits": { "type": "number", "example": 50 }, "topupPackageId": { "type": "string", "example": "pkg_100" }, "maxAttemptsPerDay": { "type": "number", "example": 3 }, "lastAttemptAt": { "type": [ "string", "null" ], "example": null }, "attemptsToday": { "type": "number", "example": 0 }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "enabled", "thresholdCredits", "topupPackageId", "maxAttemptsPerDay", "lastAttemptAt", "attemptsToday", "createdAt", "updatedAt" ] }, "UpdateAutoTopupResponse": { "type": "object", "properties": { "autoTopup": { "$ref": "#/components/schemas/AutoTopupConfig" } }, "required": [ "autoTopup" ] }, "UpdateAutoTopupRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "thresholdCredits": { "type": "integer", "exclusiveMinimum": 0 }, "topupPackageId": { "type": "string", "minLength": 1 } }, "required": [ "enabled", "thresholdCredits", "topupPackageId" ] }, "ListPaymentMethodsResponse": { "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } }, "required": [ "paymentMethods" ] }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "string", "example": "pm_1234567890" }, "type": { "type": "string", "enum": [ "card" ], "example": "card" }, "card": { "$ref": "#/components/schemas/PaymentMethodCard" }, "isDefault": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "type", "card", "isDefault", "createdAt" ] }, "PaymentMethodCard": { "type": "object", "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "example": "4242" }, "expMonth": { "type": "number", "example": 12 }, "expYear": { "type": "number", "example": 2027 } }, "required": [ "brand", "last4", "expMonth", "expYear" ] }, "CreateSetupIntentResponse": { "type": "object", "properties": { "clientSecret": { "type": "string", "example": "seti_1234567890_secret_abcdefghij" } }, "required": [ "clientSecret" ] }, "SavePaymentMethodResponse": { "type": "object", "properties": { "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" } }, "required": [ "paymentMethod" ] }, "SavePaymentMethodRequest": { "type": "object", "properties": { "paymentMethodId": { "type": "string", "example": "pm_1234567890" }, "setAsDefault": { "type": "boolean", "example": true } }, "required": [ "paymentMethodId" ] }, "DeletePaymentMethodResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "SetDefaultPaymentMethodResponse": { "type": "object", "properties": { "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" } }, "required": [ "paymentMethod" ] }, "ListAiPackagesResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/AiCreditPackage" } } }, "required": [ "packages" ] }, "AiCreditPackage": { "type": "object", "properties": { "id": { "type": "string", "example": "ai_pkg_100" }, "name": { "type": "string", "example": "100 AI Credits" }, "credits": { "type": "number", "example": 100 }, "basePrice": { "type": "integer", "example": 600, "description": "Integer minor units" }, "baseCurrency": { "type": "string", "example": "USD" }, "discountPercent": { "type": "number", "example": 0 }, "finalPrice": { "type": "integer", "example": 600, "description": "Integer minor units" }, "isActive": { "type": "boolean", "example": true }, "displayOrder": { "type": "number", "example": 1 } }, "required": [ "id", "name", "credits", "basePrice", "baseCurrency", "discountPercent", "finalPrice", "isActive", "displayOrder" ] }, "GetAiBalanceResponse": { "type": "object", "properties": { "aiBalance": { "$ref": "#/components/schemas/AiBalance" } }, "required": [ "aiBalance" ] }, "AiBalance": { "type": "object", "properties": { "balance": { "type": "number", "example": 22 }, "lifetimeCredits": { "type": "number", "example": 25 }, "lifetimeUsed": { "type": "number", "example": 3 }, "isLow": { "type": "boolean", "example": false }, "isDepleted": { "type": "boolean", "example": false } }, "required": [ "balance", "lifetimeCredits", "lifetimeUsed", "isLow", "isDepleted" ] }, "AiTopupResult": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "payment": { "$ref": "#/components/schemas/Payment" }, "creditsAdded": { "type": "number", "example": 100 }, "newBalance": { "type": "number", "example": 122 } }, "required": [ "invoice", "payment", "creditsAdded", "newBalance" ] }, "CreateAiTopupRequest": { "type": "object", "properties": { "aiPackageId": { "type": "string", "minLength": 1 }, "paymentMethodId": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "email": { "type": "string", "format": "email" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddress" } }, "required": [ "aiPackageId", "paymentMethodId" ] }, "CreateInventoryResponse": { "type": "object", "properties": { "inventory": { "$ref": "#/components/schemas/Inventory" } }, "required": [ "inventory" ] }, "Inventory": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "sourceType": { "type": "string", "enum": [ "event_occurrence_area", "product" ], "example": "event_occurrence_area", "description": "Type of inventory source" }, "eventId": { "type": [ "string", "null" ], "example": "evt_ghi789" }, "eventOccurrenceId": { "type": [ "string", "null" ], "example": "evo_jkl012" }, "eventLayoutAreaId": { "type": [ "string", "null" ], "example": "ela_mno345" }, "productId": { "type": [ "string", "null" ], "example": "prd_pqr678" }, "totalCapacity": { "type": "number", "example": 500 }, "available": { "type": "number", "example": 450 }, "reserved": { "type": "number", "example": 30 }, "confirmed": { "type": "number", "example": 20 }, "held": { "type": "number", "example": 0 }, "isAllocated": { "type": "boolean", "example": false }, "version": { "type": "number", "example": 1 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": null }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" } }, "required": [ "id", "organisationId", "accountId", "sourceType", "eventId", "eventOccurrenceId", "eventLayoutAreaId", "productId", "totalCapacity", "available", "reserved", "confirmed", "held", "isAllocated", "version", "metadata", "createdAt", "updatedAt" ] }, "ListInventoryResponse": { "type": "object", "properties": { "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/Inventory" } } }, "required": [ "inventory" ] }, "GetInventoryResponse": { "type": "object", "properties": { "inventory": { "$ref": "#/components/schemas/Inventory" } }, "required": [ "inventory" ] }, "UpdateInventoryResponse": { "type": "object", "properties": { "inventory": { "$ref": "#/components/schemas/Inventory" } }, "required": [ "inventory" ] }, "DeleteInventoryResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Inventory deleted successfully" } }, "required": [ "message" ] }, "GetAuditLogResponse": { "type": "object", "properties": { "auditLog": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } } }, "required": [ "auditLog" ] }, "AuditLogEntry": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "inventoryId": { "type": "string", "example": "inv_abc123" }, "action": { "type": "string", "example": "reserve" }, "changes": { "type": "object", "additionalProperties": {}, "example": { "quantity": 2, "type": "temporary" } }, "actorType": { "type": [ "string", "null" ], "example": "user" }, "actorId": { "type": [ "string", "null" ], "example": "usr_abc123" }, "referenceType": { "type": [ "string", "null" ], "example": "order" }, "referenceId": { "type": [ "string", "null" ], "example": "ord_def456" }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" } }, "required": [ "id", "inventoryId", "action", "changes", "actorType", "actorId", "referenceType", "referenceId", "createdAt" ] }, "BulkImportSeatsResponse": { "type": "object", "properties": { "seats": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySeat" } }, "count": { "type": "number", "example": 100 } }, "required": [ "seats", "count" ] }, "InventorySeat": { "type": "object", "properties": { "id": { "type": "string", "example": "ivs_abc123" }, "inventoryId": { "type": "string", "example": "inv_def456" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_ghi012" }, "eventLayoutSeatId": { "type": [ "string", "null" ], "example": "eas_jkl345" }, "rowName": { "type": "string", "example": "A" }, "seatNumber": { "type": "string", "example": "12" }, "status": { "type": "string", "enum": [ "available", "reserved", "confirmed", "held", "maintenance" ], "example": "available", "description": "Current status of the seat" }, "reservationId": { "type": [ "string", "null" ], "example": "ivr_mno678" }, "priceCategory": { "type": [ "string", "null" ], "example": "premium" }, "isAccessible": { "type": "boolean", "example": false }, "isCompanion": { "type": "boolean", "example": false }, "version": { "type": "number", "example": 1 }, "attributes": { "type": [ "object", "null" ], "additionalProperties": {}, "example": null }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" } }, "required": [ "id", "inventoryId", "organisationId", "accountId", "eventLayoutSeatId", "rowName", "seatNumber", "status", "reservationId", "priceCategory", "isAccessible", "isCompanion", "version", "attributes", "createdAt", "updatedAt" ] }, "ListSeatsResponse": { "type": "object", "properties": { "seats": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySeat" } } }, "required": [ "seats" ] }, "ReserveInventoryResponse": { "type": "object", "properties": { "reservation": { "$ref": "#/components/schemas/InventoryReservation" } }, "required": [ "reservation" ] }, "InventoryReservation": { "type": "object", "properties": { "id": { "type": "string", "example": "ivr_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_def456" }, "inventoryId": { "type": "string", "example": "inv_ghi789" }, "referenceType": { "type": [ "string", "null" ], "enum": [ "order", "hold", "subscription", null ], "example": "order", "description": "Type of reference for this reservation" }, "referenceId": { "type": [ "string", "null" ], "example": "ord_jkl012" }, "type": { "type": "string", "enum": [ "temporary", "confirmed", "hold", "maintenance" ], "example": "temporary", "description": "Type of reservation" }, "quantity": { "type": "number", "example": 2 }, "seatIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "example": [ "ivs_abc123", "ivs_def456" ] }, "expiresAt": { "type": [ "string", "null" ], "example": "2024-12-28T10:45:00Z" }, "reason": { "type": [ "string", "null" ], "example": "Customer checkout" }, "heldBy": { "type": [ "string", "null" ], "example": "usr_abc123" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": null }, "createdAt": { "type": "string", "example": "2024-12-28T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-12-28T14:45:00Z" } }, "required": [ "id", "organisationId", "accountId", "inventoryId", "referenceType", "referenceId", "type", "quantity", "seatIds", "expiresAt", "reason", "heldBy", "metadata", "createdAt", "updatedAt" ] }, "CheckAvailabilityResponse": { "type": "object", "properties": { "available": { "type": "boolean", "example": true }, "availableQuantity": { "type": "number", "example": 50 }, "requestedQuantity": { "type": "number", "example": 2 } }, "required": [ "available", "availableQuantity", "requestedQuantity" ] }, "ListReservationsResponse": { "type": "object", "properties": { "reservations": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryReservation" } } }, "required": [ "reservations" ] }, "GetReservationResponse": { "type": "object", "properties": { "reservation": { "$ref": "#/components/schemas/InventoryReservation" } }, "required": [ "reservation" ] }, "ConfirmReservationResponse": { "type": "object", "properties": { "reservation": { "$ref": "#/components/schemas/InventoryReservation" } }, "required": [ "reservation" ] }, "ReleaseReservationResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Reservation released successfully" } }, "required": [ "message" ] }, "ExtendReservationResponse": { "type": "object", "properties": { "reservation": { "$ref": "#/components/schemas/InventoryReservation" } }, "required": [ "reservation" ] }, "CreateHoldResponse": { "type": "object", "properties": { "reservation": { "$ref": "#/components/schemas/InventoryReservation" } }, "required": [ "reservation" ] }, "ReleaseHoldResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Hold released successfully" } }, "required": [ "message" ] }, "CreateCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": [ "string", "null" ], "example": "acc_xyz789" }, "email": { "type": "string", "example": "customer@example.com" }, "firstName": { "type": [ "string", "null" ], "example": "John" }, "lastName": { "type": [ "string", "null" ], "example": "Doe" }, "phone": { "type": [ "string", "null" ], "example": "+44 7700 900000" }, "externalId": { "type": [ "string", "null" ], "example": "ext_cust_12345" }, "isBlocked": { "type": "boolean", "example": false }, "blockedAt": { "type": [ "string", "null" ], "example": null }, "blockedReason": { "type": [ "string", "null" ], "example": null }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "loyaltyTier": "gold" } }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-20T14:45:00Z" } }, "required": [ "id", "organisationId", "accountId", "email", "firstName", "lastName", "phone", "externalId", "isBlocked", "blockedAt", "blockedReason", "metadata", "createdAt", "updatedAt" ] }, "ListCustomersResponse": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 20 }, "total": { "type": "number", "example": 150 }, "totalPages": { "type": "number", "example": 8 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "customers", "pagination" ] }, "GetCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] }, "UpdateCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] }, "BlockCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] }, "UnblockCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] }, "CreateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string", "example": "ord_abc123xyz789" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_xyz789" }, "orderNumber": { "type": "string", "example": "ORD-ABC123" }, "customerId": { "type": [ "string", "null" ], "example": "cus_abc123" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "processing", "completed", "cancelled", "refunded", "expired", "failed" ], "example": "pending" }, "currency": { "type": "string", "example": "GBP" }, "subtotal": { "type": "integer", "example": 5000 }, "totalFees": { "type": "integer", "example": 250 }, "totalTax": { "type": "integer", "example": 1000 }, "totalDiscounts": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 6250 }, "totalPaid": { "type": "integer", "example": 6250 }, "totalRefunded": { "type": "integer", "example": 0 }, "channel": { "type": [ "string", "null" ], "example": "web" }, "isGuestCheckout": { "type": "boolean", "example": false }, "customerNotes": { "type": [ "string", "null" ], "example": "Please contact me before delivery" }, "internalNotes": { "type": [ "string", "null" ], "example": "VIP customer" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "promoCode": "SUMMER20" } }, "expiresAt": { "type": [ "string", "null" ], "example": "2024-01-15T10:45:00Z" }, "confirmedAt": { "type": [ "string", "null" ], "example": null }, "completedAt": { "type": [ "string", "null" ], "example": null }, "cancelledAt": { "type": [ "string", "null" ], "example": null }, "cancellationReason": { "type": [ "string", "null" ], "example": null }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineItem" }, "description": "Order line items" }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "orderNumber", "customerId", "status", "currency", "subtotal", "totalFees", "totalTax", "totalDiscounts", "total", "totalPaid", "totalRefunded", "channel", "isGuestCheckout", "customerNotes", "internalNotes", "metadata", "expiresAt", "confirmedAt", "completedAt", "cancelledAt", "cancellationReason", "createdAt", "updatedAt" ] }, "OrderLineItem": { "type": "object", "properties": { "id": { "type": "string", "example": "oli_abc123" }, "orderId": { "type": "string", "example": "ord_abc123xyz789" }, "type": { "type": "string", "enum": [ "ticket", "product", "addon", "fee", "tax", "discount" ], "example": "ticket" }, "name": { "type": "string", "example": "General Admission" }, "description": { "type": [ "string", "null" ], "example": "Entry to main event area" }, "unitPrice": { "type": "integer", "example": 2500, "description": "Integer minor units (e.g. 2500 = £25.00)" }, "quantity": { "type": "number", "example": 2 }, "subtotal": { "type": "integer", "example": 5000, "description": "Integer minor units" }, "taxAmount": { "type": "integer", "example": 0, "description": "Integer minor units" }, "discountAmount": { "type": "integer", "example": 0, "description": "Integer minor units" }, "total": { "type": "integer", "example": 5000, "description": "Integer minor units" }, "ticketDetails": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "eventId": "evt_123" } }, "productDetails": { "type": [ "object", "null" ], "additionalProperties": {}, "example": null }, "feeDetails": { "type": [ "object", "null" ], "additionalProperties": {}, "example": null }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "source": "web" } }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "orderId", "type", "name", "description", "unitPrice", "quantity", "subtotal", "taxAmount", "discountAmount", "total", "ticketDetails", "productDetails", "feeDetails", "metadata", "createdAt", "updatedAt" ] }, "ListOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 20 }, "total": { "type": "number", "example": 150 }, "totalPages": { "type": "number", "example": 8 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "orders", "pagination" ] }, "GetOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "UpdateOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "CancelOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "TransitionOrderStatusResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "ValidateOrderResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "INVENTORY_UNAVAILABLE" }, "message": { "type": "string", "example": "Requested tickets are no longer available" }, "itemId": { "type": "string", "example": "oli_abc123" } }, "required": [ "code", "message" ] }, "description": "Validation errors if any" } }, "required": [ "valid", "errors" ] }, "AddLineItemResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "item": { "$ref": "#/components/schemas/OrderLineItem" } }, "required": [ "order", "item" ] }, "UpdateLineItemResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "item": { "$ref": "#/components/schemas/OrderLineItem" } }, "required": [ "order", "item" ] }, "RemoveLineItemResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "InitiatePaymentResponse": { "type": "object", "properties": { "paymentId": { "type": "string", "example": "pay_abc123xyz789" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed" ], "example": "pending" }, "clientSecret": { "type": [ "string", "null" ], "example": "pi_xxx_secret_yyy" }, "redirectUrl": { "type": [ "string", "null" ], "example": "https://checkout.stripe.com/pay/xxx" }, "expiresAt": { "type": [ "string", "null" ], "example": "2024-01-15T10:45:00Z" } }, "required": [ "paymentId", "status", "clientSecret", "redirectUrl", "expiresAt" ] }, "GetPaymentStatusResponse": { "type": "object", "properties": { "paymentId": { "type": [ "string", "null" ], "example": "pay_abc123xyz789" }, "status": { "type": "string", "enum": [ "none", "pending", "requires_action", "processing", "succeeded", "failed", "cancelled" ], "example": "pending" }, "amount": { "type": [ "integer", "null" ], "example": 6250, "description": "Integer minor units (e.g. 6250 = £62.50)" }, "currency": { "type": [ "string", "null" ], "example": "GBP" }, "paidAt": { "type": [ "string", "null" ], "example": null }, "failedAt": { "type": [ "string", "null" ], "example": null }, "failureReason": { "type": [ "string", "null" ], "example": null } }, "required": [ "paymentId", "status", "amount", "currency", "paidAt", "failedAt", "failureReason" ] }, "ResendOrderConfirmationResponse": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true }, "recipient": { "type": [ "string", "null" ], "example": "jane@example.com" }, "messageId": { "type": "string", "example": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817" }, "skippedReason": { "type": "string", "enum": [ "already_sent", "no_recipient", "not_configured", "order_not_confirmed" ], "example": "not_configured" }, "attachments": { "type": "integer", "example": 2, "description": "Ticket PDFs attached" } }, "required": [ "sent", "recipient", "attachments" ] }, "GetOrderPassesResponse": { "type": "object", "properties": { "passes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPass" } }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEntitlement" } }, "redemptions": { "type": "array", "items": { "$ref": "#/components/schemas/OrderRedemption" } } }, "required": [ "passes", "entitlements", "redemptions" ] }, "OrderPass": { "type": "object", "properties": { "id": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "barcode": { "type": "string", "example": "tkt_oL3OhU2Zu6Xgv4pf3txvOCpDYDkFXdgQ" }, "type": { "type": "string", "example": "ticket" }, "status": { "type": "string", "example": "active" }, "customerId": { "type": [ "string", "null" ], "example": "cus_Gk9QJ1dq" }, "holderName": { "type": [ "string", "null" ], "example": "Jamie Johnstone" }, "holderEmail": { "type": [ "string", "null" ], "example": "j@miej.co" }, "issuedAt": { "type": "string", "example": "2026-06-13T19:21:25.000Z" }, "createdAt": { "type": "string", "example": "2026-06-13T19:21:25.000Z" } }, "required": [ "id", "barcode", "type", "status", "customerId", "holderName", "holderEmail", "issuedAt", "createdAt" ] }, "OrderEntitlement": { "type": "object", "properties": { "id": { "type": "string", "example": "ent_PfK1N8UTb3MbN7nl7TiR" }, "passId": { "type": [ "string", "null" ], "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "type": { "type": "string", "example": "admission" }, "name": { "type": "string", "example": "An Evening with the Midnight Quartet - Adult" }, "status": { "type": "string", "example": "active" }, "redemptionCount": { "type": "number", "example": 0 }, "redemptionLimit": { "type": [ "number", "null" ], "example": 1 }, "orderLineItemId": { "type": "string", "example": "oli_lYbJj1kF8RB9L6qfIcpQ" }, "eventOccurrenceId": { "type": [ "string", "null" ], "example": "evoc_tGYSc512" }, "ticketTypeId": { "type": [ "string", "null" ], "example": "tty_abc123" }, "seatLabel": { "type": [ "string", "null" ], "example": "A12" }, "unitPrice": { "type": [ "number", "null" ], "example": 2500, "description": "Integer minor units" }, "currency": { "type": [ "string", "null" ], "example": "GBP" }, "createdAt": { "type": "string", "example": "2026-06-13T19:21:25.000Z" } }, "required": [ "id", "passId", "type", "name", "status", "redemptionCount", "redemptionLimit", "orderLineItemId", "eventOccurrenceId", "ticketTypeId", "seatLabel", "unitPrice", "currency", "createdAt" ] }, "OrderRedemption": { "type": "object", "properties": { "id": { "type": "string", "example": "red_3jnqRQdOeLH9bfOI6Rtn" }, "entitlementId": { "type": "string", "example": "ent_PfK1N8UTb3MbN7nl7TiR" }, "passId": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "status": { "type": "string", "example": "redeemed" }, "location": { "type": [ "string", "null" ], "example": "Main Gate" }, "deviceId": { "type": [ "string", "null" ], "example": null }, "redeemedBy": { "type": [ "string", "null" ], "example": "usr_abc123" }, "rejectionReason": { "type": [ "string", "null" ], "example": null }, "reversedAt": { "type": [ "string", "null" ], "example": null }, "reversalReason": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2026-06-13T20:10:00.000Z" } }, "required": [ "id", "entitlementId", "passId", "status", "location", "deviceId", "redeemedBy", "rejectionReason", "reversedAt", "reversalReason", "createdAt" ] }, "CreatePaymentResponse": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } }, "required": [ "payment" ] }, "GetPaymentResponse": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } }, "required": [ "payment" ] }, "CancelPaymentResponse": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } }, "required": [ "payment" ] }, "CreateRefundResponse": { "type": "object", "properties": { "refund": { "$ref": "#/components/schemas/Refund" } }, "required": [ "refund" ] }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "example": "ref_abc123xyz789" }, "paymentId": { "type": "string", "example": "pay_abc123xyz789" }, "externalRefundId": { "type": [ "string", "null" ], "example": "re_xxx" }, "amount": { "type": "integer", "example": 4850, "description": "Integer minor units (e.g. 4850 = £48.50)" }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed", "cancelled" ], "example": "succeeded" }, "reason": { "type": "string", "example": "requested_by_customer" }, "notes": { "type": [ "string", "null" ], "example": "Customer unable to attend" }, "failureCode": { "type": [ "string", "null" ], "example": null }, "failureMessage": { "type": [ "string", "null" ], "example": null }, "completedAt": { "type": [ "string", "null" ], "example": "2024-01-15T11:00:00Z" }, "failedAt": { "type": [ "string", "null" ], "example": null }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "ticketNumber": "T-001" } }, "createdAt": { "type": "string", "example": "2024-01-15T10:50:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T11:00:00Z" } }, "required": [ "id", "paymentId", "externalRefundId", "amount", "status", "reason", "notes", "failureCode", "failureMessage", "completedAt", "failedAt", "metadata", "createdAt", "updatedAt" ] }, "ListRefundsResponse": { "type": "object", "properties": { "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } }, "required": [ "refunds" ] }, "CreatePaymentProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/PaymentProvider" } }, "required": [ "provider" ] }, "PaymentProvider": { "type": "object", "properties": { "id": { "type": "string", "example": "pp_stripeXxx123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": [ "string", "null" ], "example": "acc_xyz789" }, "type": { "type": "string", "enum": [ "stripe_connect", "stripe_direct", "adyen", "square", "paypal", "cash", "bank_transfer" ], "example": "stripe_connect" }, "name": { "type": "string", "example": "Main Stripe Account" }, "description": { "type": [ "string", "null" ], "example": "Primary payment processor for online orders" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_setup" ], "example": "active" }, "integrationServiceUrl": { "type": [ "string", "null" ], "example": "https://stripe.paymentintegration.ticketlayer.com" }, "integrationServiceVersion": { "type": "string", "example": "v1" }, "configuration": { "type": "object", "additionalProperties": {}, "example": { "stripeConnectedAccountId": "acct_xxx" }, "description": "Provider-specific configuration (sensitive fields redacted)" }, "supportedPaymentTypes": { "type": "array", "items": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ] }, "example": [ "online_card", "online_wallet" ] }, "capabilities": { "$ref": "#/components/schemas/PaymentProviderCapabilities" }, "isDefault": { "type": "boolean", "example": true }, "priority": { "type": "number", "example": 100 }, "feeStructure": { "$ref": "#/components/schemas/FeeStructure" }, "applicationFee": { "$ref": "#/components/schemas/ApplicationFee" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "environment": "production" } }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "type", "name", "description", "status", "integrationServiceUrl", "integrationServiceVersion", "configuration", "supportedPaymentTypes", "capabilities", "isDefault", "priority", "feeStructure", "applicationFee", "metadata", "createdAt", "updatedAt" ] }, "PaymentProviderCapabilities": { "type": [ "object", "null" ], "properties": { "supportsInstantCapture": { "type": "boolean", "example": true }, "supportsDelayedCapture": { "type": "boolean", "example": true }, "supportsRefunds": { "type": "boolean", "example": true }, "supportsPartialRefunds": { "type": "boolean", "example": true }, "requiresCustomerAction": { "type": "boolean", "example": true }, "supportedCurrencies": { "type": "array", "items": { "type": "string" }, "example": [ "GBP", "USD", "EUR" ] }, "maxAmount": { "type": "number", "example": 10000 }, "minAmount": { "type": "number", "example": 0.5 } }, "description": "Provider capabilities" }, "FeeStructure": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "percentage_plus_fixed" ], "example": "percentage_plus_fixed" }, "percentage": { "type": "number", "example": 2.9 }, "fixed": { "type": "number", "example": 0.2 }, "currency": { "type": "string", "example": "GBP" } }, "required": [ "type" ], "description": "Fee structure" }, "ApplicationFee": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "percentage_plus_fixed" ], "example": "percentage_plus_fixed" }, "value": { "type": "number", "minimum": 0, "example": 1, "description": "Legacy single value: percent for percentage, minor units for fixed" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "example": 1, "description": "Percent of the charge" }, "fixed": { "type": "integer", "minimum": 0, "example": 10, "description": "Minor units per charge" } }, "required": [ "type" ], "description": "Application fee configuration" }, "ListPaymentProvidersResponse": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentProvider" } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 20 }, "total": { "type": "number", "example": 5 }, "totalPages": { "type": "number", "example": 1 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "providers", "pagination" ] }, "GetPaymentProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/PaymentProvider" } }, "required": [ "provider" ] }, "UpdatePaymentProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/PaymentProvider" } }, "required": [ "provider" ] }, "DeletePaymentProviderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "pp_stripeXxx123" } }, "required": [ "success", "id" ] }, "EnableTicketlayerPayResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/TicketlayerPayStatus" }, "created": { "type": "boolean" } }, "required": [ "status", "created" ] }, "TicketlayerPayStatus": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "providerId": { "type": [ "string", "null" ], "example": "ppr_tlpayXxx123" }, "providerStatus": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "pending_setup", null ] }, "connectedAccountId": { "type": [ "string", "null" ], "example": "acct_1AbCdEfGhIjKlMnO" }, "onboardingStatus": { "type": [ "string", "null" ], "enum": [ "not_started", "in_progress", "pending_verification", "complete", "restricted", "disabled", null ] }, "chargesEnabled": { "type": "boolean" }, "payoutsEnabled": { "type": "boolean" }, "detailsSubmitted": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "requirements": { "$ref": "#/components/schemas/ConnectedAccountRequirements" }, "applicationFee": { "$ref": "#/components/schemas/ApplicationFee" }, "lastSyncedAt": { "type": [ "string", "null" ] } }, "required": [ "enabled", "providerId", "providerStatus", "connectedAccountId", "onboardingStatus", "chargesEnabled", "payoutsEnabled", "detailsSubmitted", "disabledReason", "requirements", "applicationFee", "lastSyncedAt" ] }, "ConnectedAccountRequirements": { "type": [ "object", "null" ], "properties": { "status": { "type": [ "string", "null" ], "enum": [ "currently_due", "eventually_due", "past_due", null ] }, "deadline": { "type": [ "string", "null" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "identity.business_details.registered_name" }, "description": { "type": "string" }, "deadline": { "type": [ "string", "null" ] } }, "required": [ "code", "description", "deadline" ] } } }, "required": [ "status", "deadline", "entries" ] }, "ConnectOnboardingSession": { "type": "object", "properties": { "clientSecret": { "type": "string", "example": "accs_secret_..." }, "expiresAt": { "type": "string" }, "publishableKey": { "type": "string", "example": "pk_test_..." }, "connectedAccountId": { "type": "string", "example": "acct_1AbCdEfGhIjKlMnO" } }, "required": [ "clientSecret", "expiresAt", "publishableKey", "connectedAccountId" ] }, "ConnectOnboardingLinkResponse": { "type": "object", "properties": { "link": { "type": "object", "properties": { "url": { "type": "string", "example": "https://connect.stripe.com/setup/..." }, "expiresAt": { "type": "string" }, "connectedAccountId": { "type": "string" } }, "required": [ "url", "expiresAt", "connectedAccountId" ] } }, "required": [ "link" ] }, "LinkStripeConnectResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/StripeConnectProvider" }, "created": { "type": "boolean" } }, "required": [ "provider", "created" ] }, "StripeConnectProvider": { "type": "object", "properties": { "id": { "type": "string", "example": "ppr_stripeXxx123" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_setup" ] }, "defaultMode": { "type": "string", "enum": [ "direct", "connected" ] }, "publishableKey": { "type": [ "string", "null" ] }, "platformAccountId": { "type": [ "string", "null" ], "example": "acct_1PlatformXxx" }, "platformCountry": { "type": [ "string", "null" ] }, "platformCurrency": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "applicationFee": { "$ref": "#/components/schemas/ApplicationFee" }, "refundApplicationFee": { "type": "boolean" }, "webhookRegistered": { "type": "boolean" }, "connectWebhookRegistered": { "type": "boolean" }, "webhookRegistrationError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "defaultMode", "publishableKey", "platformAccountId", "platformCountry", "platformCurrency", "livemode", "applicationFee", "refundApplicationFee", "webhookRegistered", "connectWebhookRegistered", "webhookRegistrationError", "createdAt", "updatedAt" ] }, "PaymentProviderAccount": { "type": "object", "properties": { "id": { "type": "string", "example": "ppa_abc123" }, "providerId": { "type": "string" }, "accountId": { "type": "string", "example": "acc_abc123" }, "mode": { "type": "string", "enum": [ "direct", "connected" ] }, "connectedAccountId": { "type": [ "string", "null" ] }, "onboardingStatus": { "type": [ "string", "null" ], "enum": [ "not_started", "in_progress", "pending_verification", "complete", "restricted", "disabled", null ] }, "chargesEnabled": { "type": "boolean" }, "payoutsEnabled": { "type": "boolean" }, "detailsSubmitted": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ] }, "requirements": { "$ref": "#/components/schemas/ConnectedAccountRequirements" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "providerId", "accountId", "mode", "connectedAccountId", "onboardingStatus", "chargesEnabled", "payoutsEnabled", "detailsSubmitted", "disabledReason", "requirements", "lastSyncedAt", "createdAt", "updatedAt" ] }, "SalesChannelResponse": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/SalesChannel" } }, "required": [ "channel" ] }, "SalesChannel": { "type": "object", "properties": { "id": { "type": "string", "example": "sch_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_abc123" }, "name": { "type": "string", "example": "Main Website" }, "slug": { "type": "string", "example": "main-website" }, "description": { "type": [ "string", "null" ], "example": "Public web sales" }, "channelType": { "type": "string", "enum": [ "website", "embed", "box_office", "kiosk", "reseller_api", "internal" ], "example": "website" }, "channelTags": { "type": "array", "items": { "type": "string" }, "example": [ "public" ] }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "tagged" ], "example": "all" }, "channelTags": { "type": "array", "items": { "type": "string" }, "example": [ "summer-festival" ] } }, "required": [ "mode" ] }, "pricingConfig": { "type": "object", "properties": { "showMemberPricing": { "type": "boolean", "example": false }, "showOriginalPrice": { "type": "boolean", "example": true }, "includeFeesInPrice": { "type": "boolean", "example": false } }, "required": [ "showMemberPricing", "showOriginalPrice", "includeFeesInPrice" ] }, "customerConfig": { "type": "object", "properties": { "requireLogin": { "type": "boolean", "example": false }, "allowGuestCheckout": { "type": "boolean", "example": true }, "collectPhone": { "type": "boolean", "example": false }, "collectAddress": { "type": "boolean", "example": false } }, "required": [ "requireLogin", "allowGuestCheckout", "collectPhone", "collectAddress" ] }, "reservationTtlSeconds": { "type": "number", "example": 900 }, "checkoutTtlSeconds": { "type": "number", "example": 300 }, "customerFacing": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "subdomain": { "type": "string", "example": "tickets" }, "customDomain": { "type": "string", "example": "tickets.example.com" }, "allowedOrigins": { "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ] }, "magicLinkBaseUrl": { "type": "string", "example": "https://tickets.example.com" }, "partnerIdentity": { "type": "object", "properties": { "issuer": { "type": "string", "example": "https://partner.example.com" }, "publicKeyPem": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----..." }, "algorithm": { "type": "string", "example": "RS256" } }, "required": [ "issuer", "publicKeyPem", "algorithm" ] } }, "required": [ "enabled", "allowedOrigins" ] }, "receivingAccountId": { "type": "string", "example": "acc_abc123" }, "feeProfileId": { "type": [ "string", "null" ], "example": "sfp_abc123" }, "themeId": { "type": [ "string", "null" ], "example": "sct_abc123" }, "isActive": { "type": "boolean", "example": true }, "isDeleted": { "type": "boolean", "example": false }, "deletedAt": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "name", "slug", "description", "channelType", "channelTags", "eventFilter", "pricingConfig", "customerConfig", "reservationTtlSeconds", "checkoutTtlSeconds", "customerFacing", "receivingAccountId", "feeProfileId", "themeId", "isActive", "isDeleted", "deletedAt", "createdAt", "updatedAt" ] }, "ListSalesChannelsResponse": { "type": "object", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/SalesChannel" } } }, "required": [ "channels" ] }, "DeleteSalesChannelResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } }, "required": [ "deleted" ] }, "IssueSalesChannelKeyResponse": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/IssuedSalesChannelKey" }, "keyMaterial": { "type": "string", "example": "tlsk_abc123...", "description": "The key itself. For secret keys this is shown exactly once." }, "warning": { "type": "string", "example": "Store this key securely. It will not be shown again and must never be used in a browser." } }, "required": [ "key", "keyMaterial" ] }, "IssuedSalesChannelKey": { "type": "object", "properties": { "id": { "type": "string", "example": "schk_abc123" }, "channelId": { "type": "string", "example": "sch_abc123" }, "keyType": { "type": "string", "enum": [ "publishable", "secret" ], "example": "secret" }, "name": { "type": "string", "example": "Production key" }, "last4": { "type": "string", "example": "a1b2" }, "status": { "type": "string", "enum": [ "active", "revoked", "compromised" ], "example": "active" }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "channelId", "keyType", "name", "last4", "status", "createdAt" ] }, "ListSalesChannelKeysResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/SalesChannelKey" } } }, "required": [ "keys" ] }, "SalesChannelKey": { "type": "object", "properties": { "id": { "type": "string", "example": "schk_abc123" }, "channelId": { "type": "string", "example": "sch_abc123" }, "keyType": { "type": "string", "enum": [ "publishable", "secret" ], "example": "publishable" }, "name": { "type": "string", "example": "Website key" }, "publishableKey": { "type": [ "string", "null" ], "example": "tlpk_abc123...", "description": "Full key material for publishable keys; null for secret keys" }, "last4": { "type": "string", "example": "a1b2" }, "status": { "type": "string", "enum": [ "active", "revoked", "compromised" ], "example": "active" }, "lastUsedAt": { "type": [ "string", "null" ], "example": "2026-01-15T10:30:00Z" }, "revokedAt": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "channelId", "keyType", "name", "publishableKey", "last4", "status", "lastUsedAt", "revokedAt", "createdAt" ] }, "RevokeSalesChannelKeyResponse": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "example": "schk_abc123" }, "status": { "type": "string", "enum": [ "active", "revoked", "compromised" ], "example": "revoked" }, "revokedAt": { "type": [ "string", "null" ], "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "status", "revokedAt" ] } }, "required": [ "key" ] }, "SalesChannelListingResponse": { "type": "object", "properties": { "listing": { "$ref": "#/components/schemas/SalesChannelListing" } }, "required": [ "listing" ] }, "SalesChannelListing": { "type": "object", "properties": { "id": { "type": "string", "example": "schl_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "channelId": { "type": "string", "example": "sch_abc123" }, "eventId": { "type": "string", "example": "evt_abc123" }, "saleStartsAt": { "type": [ "string", "null" ], "example": "2026-02-01T09:00:00Z" }, "saleEndsAt": { "type": [ "string", "null" ], "example": null }, "isActive": { "type": "boolean", "example": true }, "createdBy": { "type": [ "string", "null" ], "example": "usr_abc123" }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "channelId", "eventId", "saleStartsAt", "saleEndsAt", "isActive", "createdBy", "createdAt", "updatedAt" ] }, "ListSalesChannelListingsResponse": { "type": "object", "properties": { "listings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesChannelListing" } } }, "required": [ "listings" ] }, "DeleteSalesChannelListingResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } }, "required": [ "deleted" ] }, "StaffCartResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/StaffCart" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StaffCartItem" } } }, "required": [ "cart", "items" ] }, "StaffCart": { "type": "object", "properties": { "id": { "type": "string", "example": "crt_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_abc123" }, "channelId": { "type": "string", "example": "sch_abc123" }, "status": { "type": "string", "enum": [ "active", "checked_out", "expired", "abandoned" ], "example": "active" }, "customerId": { "type": [ "string", "null" ], "example": "cus_abc123" }, "currency": { "type": [ "string", "null" ], "example": "GBP" }, "expiresAt": { "type": "string", "example": "2026-01-15T10:45:00Z" }, "orderId": { "type": [ "string", "null" ], "example": null }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "source": "boxoffice" } }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "channelId", "status", "customerId", "currency", "expiresAt", "orderId", "metadata", "createdAt", "updatedAt" ] }, "StaffCartItem": { "type": "object", "properties": { "id": { "type": "string", "example": "crti_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "cartId": { "type": "string", "example": "crt_abc123" }, "eventOccurrenceId": { "type": "string", "example": "occ_abc123" }, "categoryId": { "type": "string", "example": "cat_abc123" }, "ticketTypeId": { "type": "string", "example": "ttp_abc123" }, "eventLayoutAreaId": { "type": [ "string", "null" ], "example": null }, "eventLayoutSeatId": { "type": [ "string", "null" ], "example": null }, "quantity": { "type": "number", "example": 2 }, "reservationId": { "type": "string", "example": "rsv_abc123" }, "priceSnapshot": { "type": "object", "properties": { "unitPrice": { "type": "number", "example": 25 }, "currency": { "type": "string", "example": "GBP" }, "categoryName": { "type": "string", "example": "Stalls" }, "ticketTypeName": { "type": "string", "example": "Adult" }, "eventId": { "type": "string", "example": "evt_abc123" }, "eventName": { "type": "string", "example": "Summer Gala" }, "priceSchemeId": { "type": "string", "example": "prs_abc123" } }, "required": [ "unitPrice", "currency", "categoryName", "ticketTypeName", "eventId", "eventName", "priceSchemeId" ] }, "notes": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "cartId", "eventOccurrenceId", "categoryId", "ticketTypeId", "eventLayoutAreaId", "eventLayoutSeatId", "quantity", "reservationId", "priceSnapshot", "notes", "createdAt" ] }, "StaffCheckoutResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/StaffCart" }, "order": { "$ref": "#/components/schemas/StaffSalesOrder" } }, "required": [ "cart", "order" ] }, "StaffSalesOrder": { "type": "object", "properties": { "id": { "type": "string", "example": "ord_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_abc123" }, "orderNumber": { "type": "string", "example": "ORD-ABC123" }, "customerId": { "type": [ "string", "null" ], "example": "cus_abc123" }, "status": { "type": "string", "example": "pending" }, "paymentStatus": { "type": "string", "example": "unpaid" }, "currency": { "type": "string", "example": "GBP" }, "subtotal": { "type": "integer", "example": 5000 }, "totalFees": { "type": "integer", "example": 250 }, "totalTax": { "type": "integer", "example": 0 }, "totalPaid": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 5250 }, "expiresAt": { "type": [ "string", "null" ], "example": "2026-01-15T10:45:00Z" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StaffSalesOrderLineItem" } }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "orderNumber", "customerId", "status", "paymentStatus", "currency", "subtotal", "totalFees", "totalTax", "totalPaid", "total", "expiresAt", "items", "createdAt", "updatedAt" ] }, "StaffSalesOrderLineItem": { "type": "object", "properties": { "id": { "type": "string", "example": "oli_abc123" }, "orderId": { "type": "string", "example": "ord_abc123" }, "type": { "type": "string", "example": "ticket" }, "name": { "type": "string", "example": "General Admission" }, "description": { "type": [ "string", "null" ], "example": null }, "unitPrice": { "type": "integer", "example": 2500, "description": "Integer minor units (e.g. 2500 = £25.00)" }, "quantity": { "type": "number", "example": 2 }, "subtotal": { "type": "integer", "example": 5000, "description": "Integer minor units" } }, "required": [ "id", "orderId", "type", "name", "description", "unitPrice", "quantity", "subtotal" ] }, "PresaleCodeResponse": { "type": "object", "properties": { "presaleCode": { "$ref": "#/components/schemas/PresaleCode" } }, "required": [ "presaleCode" ] }, "PresaleCode": { "type": "object", "properties": { "id": { "type": "string", "example": "psc_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": "string", "example": "acc_abc123" }, "code": { "type": "string", "example": "EARLYBIRD-2026" }, "benefit": { "type": "string", "example": "presale.summer-gala" }, "channelId": { "type": [ "string", "null" ], "example": null }, "maxRedemptions": { "type": [ "number", "null" ], "example": 500 }, "redemptionCount": { "type": "number", "example": 42 }, "expiresAt": { "type": [ "string", "null" ], "example": "2026-03-01T00:00:00Z" }, "benefitExpiresAt": { "type": [ "string", "null" ], "example": null }, "isActive": { "type": "boolean", "example": true }, "createdBy": { "type": [ "string", "null" ], "example": "usr_abc123" }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "accountId", "code", "benefit", "channelId", "maxRedemptions", "redemptionCount", "expiresAt", "benefitExpiresAt", "isActive", "createdBy", "createdAt", "updatedAt" ] }, "ListPresaleCodesResponse": { "type": "object", "properties": { "presaleCodes": { "type": "array", "items": { "$ref": "#/components/schemas/PresaleCode" } } }, "required": [ "presaleCodes" ] }, "FeeProfileResponse": { "type": "object", "properties": { "feeProfile": { "$ref": "#/components/schemas/FeeProfile" } }, "required": [ "feeProfile" ] }, "FeeProfile": { "type": "object", "properties": { "id": { "type": "string", "example": "sfp_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Standard web fees" }, "serviceFeeEnabled": { "type": "boolean", "example": true }, "serviceFeePercent": { "type": [ "string", "null" ], "example": "0.0500", "description": "Rate fraction" }, "serviceFeeFixed": { "type": [ "integer", "null" ], "example": null, "description": "Integer minor units" }, "serviceFeeLabel": { "type": [ "string", "null" ], "example": "Service fee" }, "isDeleted": { "type": "boolean", "example": false }, "deletedAt": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "organisationId", "name", "serviceFeeEnabled", "serviceFeePercent", "serviceFeeFixed", "serviceFeeLabel", "isDeleted", "deletedAt", "createdAt", "updatedAt" ] }, "ListFeeProfilesResponse": { "type": "object", "properties": { "feeProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/FeeProfile" } } }, "required": [ "feeProfiles" ] }, "DeleteFeeProfileResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } }, "required": [ "deleted" ] }, "GetSalesListingsResponse": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/SalesChannelSummary" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/SalesListing" } } }, "required": [ "channel", "listings" ] }, "SalesChannelSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "SalesListing": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "saleStartsAt": { "type": [ "string", "null" ], "example": "2026-02-01T09:00:00Z" }, "saleEndsAt": { "type": [ "string", "null" ], "example": null }, "name": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "venueName": { "type": [ "string", "null" ] }, "venueCity": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "nextOccurrenceAt": { "type": [ "string", "null" ] } }, "required": [ "id", "eventId", "saleStartsAt", "saleEndsAt", "name", "subtitle", "shortDescription", "imageUrl", "venueName", "venueCity", "priceFrom", "currency", "nextOccurrenceAt" ], "additionalProperties": false }, "SalesMagicLinkResponse": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true, "description": "Always true - success is reported regardless of whether the contact exists (no account enumeration)" } }, "required": [ "sent" ] }, "SalesCustomerTokenResponse": { "type": "object", "properties": { "customerToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIs..." }, "expiresIn": { "type": "number", "example": 1800, "description": "Token lifetime in seconds" }, "customer": { "$ref": "#/components/schemas/SalesCustomer" } }, "required": [ "customerToken", "expiresIn", "customer" ] }, "SalesCustomer": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "firstName", "lastName" ], "additionalProperties": false }, "SalesCartResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/SalesCart" } }, "required": [ "cart" ] }, "SalesCart": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "example": "2026-01-15T10:45:00Z" }, "orderId": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCartItem" } }, "itemsSubtotal": { "type": "number" } }, "required": [ "id", "status", "currency", "expiresAt", "orderId", "items", "itemsSubtotal" ], "additionalProperties": false }, "SalesCartItem": { "type": "object", "properties": { "id": { "type": "string" }, "eventOccurrenceId": { "type": "string" }, "eventName": { "type": "string" }, "categoryName": { "type": "string" }, "ticketTypeName": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "subtotal": { "type": "number" } }, "required": [ "id", "eventOccurrenceId", "eventName", "categoryName", "ticketTypeName", "quantity", "unitPrice", "currency", "subtotal" ], "additionalProperties": false }, "SalesCheckoutResponse": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/SalesCart" }, "order": { "$ref": "#/components/schemas/SalesOrder" }, "orderAccessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIs...", "description": "Possession-based guest access token for reading/paying this order without a customer login" } }, "required": [ "cart", "order", "orderAccessToken" ] }, "SalesOrder": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "status": { "type": "string" }, "paymentStatus": { "type": "string" }, "currency": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrderItem" } }, "subtotal": { "type": "number" }, "totalFees": { "type": "number" }, "totalTax": { "type": "number" }, "total": { "type": "number" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/SalesTicket" } }, "expiresAt": { "type": [ "string", "null" ], "example": "2026-01-15T10:45:00Z" }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "orderNumber", "status", "paymentStatus", "currency", "items", "subtotal", "totalFees", "totalTax", "total", "tickets", "expiresAt", "createdAt" ], "additionalProperties": false }, "SalesOrderItem": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "subtotal": { "type": "number" } }, "required": [ "name", "description", "type", "quantity", "unitPrice", "subtotal" ], "additionalProperties": false }, "SalesTicket": { "type": "object", "properties": { "id": { "type": "string" }, "barcode": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "holderName": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "admissionStatus": { "type": "string" }, "eventOccurrenceId": { "type": [ "string", "null" ] }, "seatLabel": { "type": [ "string", "null" ] } }, "required": [ "id", "barcode", "type", "status", "holderName", "name", "admissionStatus", "eventOccurrenceId", "seatLabel" ], "additionalProperties": false }, "ListMySalesOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" } } }, "required": [ "orders" ] }, "GetSalesOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/SalesOrder" } }, "required": [ "order" ] }, "CreateSalesOrderPaymentResponse": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/SalesPayment" } }, "required": [ "payment" ] }, "SalesPayment": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "status": { "type": "string" }, "paymentType": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "providerClientSecret": { "type": [ "string", "null" ] }, "externalPaymentUrl": { "type": [ "string", "null" ] }, "publishableKey": { "type": [ "string", "null" ] }, "connectedAccountId": { "type": [ "string", "null" ] }, "providerType": { "type": [ "string", "null" ] } }, "required": [ "id", "orderId", "status", "paymentType", "amount", "currency", "providerClientSecret", "externalPaymentUrl", "publishableKey", "connectedAccountId", "providerType" ], "additionalProperties": false }, "CreateSalesRefundRequestResponse": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/SalesRefundRequest" } }, "required": [ "request" ] }, "SalesRefundRequest": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "example": "2026-01-15T10:30:00Z" } }, "required": [ "id", "orderId", "type", "status", "reason", "createdAt" ], "additionalProperties": false }, "SalesCustomerResponse": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/SalesCustomer" } }, "required": [ "customer" ] }, "RedeemSalesPresaleCodeResponse": { "type": "object", "properties": { "benefit": { "type": "string", "example": "presale.summer-gala" }, "alreadyHeld": { "type": "boolean", "example": false, "description": "True if the customer already held this benefit" } }, "required": [ "benefit", "alreadyHeld" ] }, "SalesResolveChannelResponse": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/SalesChannelSummary" }, "publishableKey": { "type": [ "string", "null" ], "example": "tlpk_abc123", "description": "The channel's active publishable key (public by design), or null if none is issued" } }, "required": [ "channel", "publishableKey" ] }, "SalesEventDetailResponse": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "heroImageUrl": { "type": [ "string", "null" ] }, "presentation": { "type": [ "object", "null" ], "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hero", "cinema" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type", "size" ], "additionalProperties": false }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 20 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 70 ] } ] }, "position": { "type": "string", "enum": [ "bottom", "center" ] } }, "required": [ "strength", "position" ], "additionalProperties": false }, "twoColumnSplit": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] }, "navbar": { "type": "object", "properties": { "transparent": { "type": "boolean" } }, "additionalProperties": false }, "buttonSize": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "additionalProperties": false }, "venueId": { "type": [ "string", "null" ] }, "venueName": { "type": [ "string", "null" ] }, "venueCity": { "type": [ "string", "null" ] }, "priceFrom": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "occurrences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "startDate": { "type": "string" }, "startTime": { "type": "string" }, "endDate": { "type": "string" }, "endTime": { "type": "string" }, "status": { "type": "string" }, "ticketTypes": { "type": "array", "items": { "type": "object", "properties": { "ticketTypeId": { "type": "string" }, "ticketTypeName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "categoryId": { "type": "string" }, "categoryName": { "type": "string" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "ticketTypeId", "ticketTypeName", "description", "categoryId", "categoryName", "unitPrice", "currency" ], "additionalProperties": false } } }, "required": [ "id", "startsAt", "endsAt", "timezone", "startDate", "startTime", "endDate", "endTime", "status", "ticketTypes" ], "additionalProperties": false } } }, "required": [ "id", "name", "subtitle", "description", "shortDescription", "status", "imageUrl", "heroImageUrl", "presentation", "venueId", "venueName", "venueCity", "priceFrom", "currency", "timezone", "occurrences" ], "additionalProperties": false } }, "required": [ "event" ] }, "SalesThemeResponse": { "type": "object", "properties": { "theme": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "additionalProperties": {} }, "colors": { "type": "object", "additionalProperties": {} }, "typography": { "type": "object", "additionalProperties": {} }, "shape": { "type": "object", "additionalProperties": {} }, "design": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "id", "name", "brand", "colors", "typography", "shape" ], "additionalProperties": false } }, "required": [ "theme" ] }, "ThemeListResponse": { "type": "object", "properties": { "themes": { "type": "array", "items": { "$ref": "#/components/schemas/Theme" } } }, "required": [ "themes" ] }, "Theme": { "type": "object", "properties": { "id": { "type": "string", "example": "sct_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Midnight" }, "description": { "type": [ "string", "null" ], "example": "Dark theme for evening events" }, "extendsThemeId": { "type": [ "string", "null" ], "example": "sct_base123" }, "isBaseTheme": { "type": "boolean", "example": false }, "isActive": { "type": "boolean", "example": true }, "brand": { "type": "object", "properties": { "logoUrl": { "type": "string", "example": "https://cdn.example.com/logo.svg" }, "logoDarkUrl": { "type": "string" }, "faviconUrl": { "type": "string" }, "displayName": { "type": "string", "example": "Acme Tickets" } } }, "colors": { "type": "object", "properties": { "primary": { "type": "string", "example": "#7C3AED" }, "primaryForeground": { "type": "string" }, "secondary": { "type": "string" }, "secondaryForeground": { "type": "string" }, "accent": { "type": "string" }, "accentForeground": { "type": "string" }, "background": { "type": "string" }, "foreground": { "type": "string" }, "muted": { "type": "string" }, "mutedForeground": { "type": "string" }, "border": { "type": "string" }, "input": { "type": "string" }, "ring": { "type": "string" }, "success": { "type": "string" }, "successForeground": { "type": "string" }, "warning": { "type": "string" }, "warningForeground": { "type": "string" }, "destructive": { "type": "string" }, "destructiveForeground": { "type": "string" } } }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "example": "Inter, sans-serif" }, "fontFamilyMono": { "type": "string" }, "baseSize": { "type": "string", "example": "16px" }, "scaleRatio": { "type": "number", "example": 1.25 } } }, "shape": { "type": "object", "properties": { "radiusNone": { "type": "string" }, "radiusSm": { "type": "string" }, "radiusMd": { "type": "string", "example": "0.5rem" }, "radiusLg": { "type": "string" }, "radiusFull": { "type": "string" } } }, "design": { "$ref": "#/components/schemas/ThemeDesign" }, "createdAt": { "type": "string", "example": "2026-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-01-01T00:00:00.000Z" } }, "required": [ "id", "organisationId", "name", "description", "extendsThemeId", "isBaseTheme", "isActive", "brand", "colors", "typography", "shape", "design", "createdAt", "updatedAt" ] }, "ThemeDesign": { "type": [ "object", "null" ], "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cinema", "hero" ], "example": "cinema" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "example": "large" } }, "required": [ "type", "size" ] }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 70 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 20 ] } ], "example": 50 }, "position": { "type": "string", "enum": [ "bottom", "center" ], "example": "bottom" } }, "required": [ "strength", "position" ] } } }, "ThemeResponse": { "type": "object", "properties": { "theme": { "$ref": "#/components/schemas/Theme" } }, "required": [ "theme" ] }, "ThemeBrandInput": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "logoDarkUrl": { "type": "string" }, "faviconUrl": { "type": "string" }, "displayName": { "type": "string" } } }, "ThemeColorsInput": { "type": "object", "properties": { "primary": { "type": "string" }, "primaryForeground": { "type": "string" }, "secondary": { "type": "string" }, "secondaryForeground": { "type": "string" }, "accent": { "type": "string" }, "accentForeground": { "type": "string" }, "background": { "type": "string" }, "foreground": { "type": "string" }, "muted": { "type": "string" }, "mutedForeground": { "type": "string" }, "border": { "type": "string" }, "input": { "type": "string" }, "ring": { "type": "string" }, "success": { "type": "string" }, "successForeground": { "type": "string" }, "warning": { "type": "string" }, "warningForeground": { "type": "string" }, "destructive": { "type": "string" }, "destructiveForeground": { "type": "string" } } }, "ThemeTypographyInput": { "type": "object", "properties": { "fontFamily": { "type": "string" }, "fontFamilyMono": { "type": "string" }, "baseSize": { "type": "string" }, "scaleRatio": { "type": "number" } } }, "ThemeShapeInput": { "type": "object", "properties": { "radiusNone": { "type": "string" }, "radiusSm": { "type": "string" }, "radiusMd": { "type": "string" }, "radiusLg": { "type": "string" }, "radiusFull": { "type": "string" } } }, "ThemeDesignInput": { "type": "object", "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cinema", "hero" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type", "size" ] }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 70 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 20 ] } ] }, "position": { "type": "string", "enum": [ "bottom", "center" ] } }, "required": [ "strength", "position" ] } }, "additionalProperties": {} }, "ResolvedThemeResponse": { "type": "object", "properties": { "theme": { "$ref": "#/components/schemas/ResolvedTheme" } }, "required": [ "theme" ] }, "ResolvedTheme": { "type": "object", "properties": { "id": { "type": "string", "example": "sct_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "name": { "type": "string", "example": "Midnight" }, "description": { "type": [ "string", "null" ] }, "extendsThemeId": { "type": [ "string", "null" ], "example": "sct_base123" }, "isBaseTheme": { "type": "boolean", "example": false }, "isActive": { "type": "boolean", "example": true }, "brand": { "type": "object", "properties": { "logoUrl": { "type": "string", "example": "https://cdn.example.com/logo.svg" }, "logoDarkUrl": { "type": "string" }, "faviconUrl": { "type": "string" }, "displayName": { "type": "string", "example": "Acme Tickets" } } }, "colors": { "type": "object", "properties": { "primary": { "type": "string", "example": "#7C3AED" }, "primaryForeground": { "type": "string" }, "secondary": { "type": "string" }, "secondaryForeground": { "type": "string" }, "accent": { "type": "string" }, "accentForeground": { "type": "string" }, "background": { "type": "string" }, "foreground": { "type": "string" }, "muted": { "type": "string" }, "mutedForeground": { "type": "string" }, "border": { "type": "string" }, "input": { "type": "string" }, "ring": { "type": "string" }, "success": { "type": "string" }, "successForeground": { "type": "string" }, "warning": { "type": "string" }, "warningForeground": { "type": "string" }, "destructive": { "type": "string" }, "destructiveForeground": { "type": "string" } } }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "example": "Inter, sans-serif" }, "fontFamilyMono": { "type": "string" }, "baseSize": { "type": "string", "example": "16px" }, "scaleRatio": { "type": "number", "example": 1.25 } } }, "shape": { "type": "object", "properties": { "radiusNone": { "type": "string" }, "radiusSm": { "type": "string" }, "radiusMd": { "type": "string", "example": "0.5rem" }, "radiusLg": { "type": "string" }, "radiusFull": { "type": "string" } } }, "design": { "$ref": "#/components/schemas/ThemeDesign" } }, "required": [ "id", "organisationId", "name", "description", "extendsThemeId", "isBaseTheme", "isActive", "brand", "colors", "typography", "shape", "design" ] }, "DeleteThemeResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } }, "required": [ "deleted" ] }, "RedeemPassResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "valid", "duplicate", "void" ], "example": "valid", "description": "valid = redeemed now; duplicate = already redeemed (limit reached); void = pass/entitlement not redeemable" }, "reason": { "type": "string", "example": "already_redeemed" }, "pass": { "type": "object", "properties": { "id": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "status": { "type": "string", "example": "active" } }, "required": [ "id", "status" ] }, "entitlement": { "type": "object", "properties": { "id": { "type": "string", "example": "ent_PfK1N8UTb3MbN7nl7TiR" }, "type": { "type": "string", "example": "admission" }, "name": { "type": "string", "example": "An Evening with the Midnight Quartet - Adult" }, "status": { "type": "string", "example": "fully_redeemed" }, "redemptionCount": { "type": "number", "example": 1 }, "redemptionLimit": { "type": [ "number", "null" ], "example": 1 }, "eventOccurrenceId": { "type": [ "string", "null" ], "example": "evoc_tGYSc512" }, "seatLabel": { "type": [ "string", "null" ], "example": "A12" } }, "required": [ "id", "type", "name", "status", "redemptionCount", "redemptionLimit", "eventOccurrenceId", "seatLabel" ] }, "redemption": { "type": "object", "properties": { "id": { "type": "string", "example": "red_abc123" }, "redeemedAt": { "type": "string", "example": "2026-06-13T19:21:25.000Z" } }, "required": [ "id", "redeemedAt" ] } }, "required": [ "outcome", "pass", "entitlement" ] }, "ListTicketTemplatesResponse": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TicketTemplate" } } }, "required": [ "templates" ] }, "TicketTemplate": { "type": "object", "properties": { "id": { "type": "string", "example": "tpl_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": [ "string", "null" ], "example": null }, "name": { "type": "string", "example": "Standard eticket" }, "type": { "type": "string", "example": "eticket" }, "description": { "type": [ "string", "null" ], "example": null }, "layout": { "type": "object", "properties": { "page": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "background": { "type": "object", "properties": { "color": { "type": "string" } }, "additionalProperties": {} } }, "required": [ "width", "height" ], "additionalProperties": {} }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "qr", "barcode", "image", "rect" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "id", "type", "x", "y", "width", "height" ], "additionalProperties": {} } } }, "required": [ "page", "blocks" ], "description": "Renderer-agnostic ticket layout: page + positioned blocks (points)." }, "version": { "type": "number", "example": 1 }, "scopeEventId": { "type": [ "string", "null" ], "example": "evt_yf0BrApW" }, "scopeTicketTypeId": { "type": [ "string", "null" ], "example": null }, "scopeChannelId": { "type": [ "string", "null" ], "example": null }, "themeId": { "type": [ "string", "null" ], "example": null }, "status": { "type": "string", "example": "active" }, "isDefault": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "example": "2026-06-13T19:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-13T19:00:00.000Z" } }, "required": [ "id", "organisationId", "accountId", "name", "type", "description", "layout", "version", "scopeEventId", "scopeTicketTypeId", "scopeChannelId", "themeId", "status", "isDefault", "createdAt", "updatedAt" ] }, "TicketTemplateResponse": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/TicketTemplate" } }, "required": [ "template" ] }, "DeleteTicketTemplateResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "ListAssetsResponse": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "required": [ "assets" ] }, "Asset": { "type": "object", "properties": { "id": { "type": "string", "example": "ast_abc123" }, "organisationId": { "type": "string", "example": "org_xyz789" }, "accountId": { "type": [ "string", "null" ], "example": null }, "name": { "type": [ "string", "null" ], "example": "Festival hero banner" }, "purpose": { "type": "string", "example": "event_image" }, "ownerType": { "type": [ "string", "null" ], "example": "event" }, "ownerId": { "type": [ "string", "null" ], "example": "evt_yf0BrApW" }, "filename": { "type": [ "string", "null" ], "example": "hero.png" }, "contentType": { "type": "string", "example": "image/png" }, "sizeBytes": { "type": "number", "example": 84213 }, "storageDriver": { "type": "string", "example": "local" }, "storageBucket": { "type": [ "string", "null" ], "example": null }, "storageKey": { "type": "string", "example": "org_xyz789/events/ast_abc123.png" }, "url": { "type": "string", "example": "https://api.local.t9r.dev/assets/org_xyz789/events/ast_abc123.png" }, "cdn": { "type": "boolean", "example": false }, "cdnUrl": { "type": [ "string", "null" ], "example": null }, "visibility": { "type": "string", "example": "public" }, "metadata": { "type": "object", "additionalProperties": {}, "example": {} }, "uploadedBy": { "type": [ "string", "null" ], "example": "usr_123" }, "createdAt": { "type": "string", "example": "2026-06-14T19:00:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-06-14T19:00:00.000Z" } }, "required": [ "id", "organisationId", "accountId", "name", "purpose", "ownerType", "ownerId", "filename", "contentType", "sizeBytes", "storageDriver", "storageBucket", "storageKey", "url", "cdn", "cdnUrl", "visibility", "metadata", "uploadedBy", "createdAt", "updatedAt" ] }, "AssetResponse": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Asset" } }, "required": [ "asset" ] }, "DeleteAssetResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "ReportSummaryResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "$ref": "#/components/schemas/ReportCurrencyTotals" } }, "filters": { "type": "object", "properties": { "eventId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } } } }, "required": [ "currencies", "filters" ] } }, "required": [ "status", "data" ] }, "ReportCurrencyTotals": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ], "example": "GBP" }, "grossRevenue": { "type": "number", "example": 70050, "description": "Integer minor units" }, "netToOrganiser": { "type": "number", "example": 63045 }, "platformFees": { "type": "number", "example": 4203 }, "taxCollected": { "type": "number", "example": 2802 }, "discounts": { "type": "number", "example": 0 }, "ticketsSold": { "type": "number", "example": 30 }, "orderCount": { "type": "number", "example": 7 }, "aov": { "type": "number", "example": 10007, "description": "Average order value, minor units" } }, "required": [ "currency", "grossRevenue", "netToOrganiser", "platformFees", "taxCollected", "discounts", "ticketsSold", "orderCount", "aov" ] }, "ReportTimeseriesResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "example": "2026-06-10T00:00:00.000" }, "currency": { "type": [ "string", "null" ], "example": "GBP" }, "grossRevenue": { "type": "number", "example": 12500 }, "ticketsSold": { "type": "number", "example": 5 } }, "required": [ "date", "currency", "grossRevenue", "ticketsSold" ] } }, "granularity": { "type": "string", "example": "day" }, "filters": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "series", "granularity", "filters" ] } }, "required": [ "status", "data" ] }, "ReportInventoryResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "occurrences": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": [ "string", "null" ] }, "occurrenceId": { "type": [ "string", "null" ] }, "totalCapacity": { "type": "number" }, "available": { "type": "number" }, "reserved": { "type": "number" }, "confirmed": { "type": "number" }, "held": { "type": "number" }, "sellThroughPct": { "type": "number", "example": 42.5 }, "utilisationPct": { "type": "number", "example": 48 } }, "required": [ "eventId", "occurrenceId", "totalCapacity", "available", "reserved", "confirmed", "held", "sellThroughPct", "utilisationPct" ] } }, "filters": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "occurrences", "filters" ] } }, "required": [ "status", "data" ] }, "ReportMetaResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "models" ] } }, "required": [ "status", "data" ] }, "ReportQueryResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "query": { "type": "object", "additionalProperties": {} } }, "required": [ "rows", "query" ] } }, "required": [ "status", "data" ] }, "SavedReportListResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/SavedReport" } } }, "required": [ "reports" ] } }, "required": [ "status", "data" ] }, "SavedReport": { "type": "object", "properties": { "id": { "type": "string", "example": "rpt_abc12345" }, "organisationId": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "name": { "type": "string", "example": "Revenue by channel" }, "description": { "type": [ "string", "null" ] }, "query": { "type": "object", "additionalProperties": {} }, "params": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "viz": { "type": "object", "additionalProperties": {} }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organisationId", "accountId", "name", "description", "query", "params", "viz", "createdBy", "createdAt", "updatedAt" ] }, "SavedReportResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "report": { "$ref": "#/components/schemas/SavedReport" } }, "required": [ "report" ] } }, "required": [ "status", "data" ] }, "SavedReportDeleteResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } }, "required": [ "status", "data" ] }, "DashboardListResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "dashboards": { "type": "array", "items": { "$ref": "#/components/schemas/Dashboard" } } }, "required": [ "dashboards" ] } }, "required": [ "status", "data" ] }, "Dashboard": { "type": "object", "properties": { "id": { "type": "string", "example": "dsh_abc12345" }, "organisationId": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "name": { "type": "string", "example": "Sales overview" }, "description": { "type": [ "string", "null" ] }, "layout": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "globalFilters": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "isSystem": { "type": "boolean" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organisationId", "accountId", "name", "description", "layout", "globalFilters", "isSystem", "createdBy", "createdAt", "updatedAt" ] }, "DashboardResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "dashboard": { "$ref": "#/components/schemas/Dashboard" } }, "required": [ "dashboard" ] } }, "required": [ "status", "data" ] }, "DashboardDeleteResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } }, "required": [ "status", "data" ] }, "ReportTemplateListResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "sales-overview" }, "name": { "type": "string" }, "description": { "type": "string" }, "tileCount": { "type": "number" } }, "required": [ "key", "name", "description", "tileCount" ] } } }, "required": [ "templates" ] } }, "required": [ "status", "data" ] }, "CreateWebhookEndpoint": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://hooks.example.com/tl" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "eventTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50, "example": [ "order.confirmed", "ticket.issued" ] } }, "required": [ "accountId", "url" ] }, "UpdateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "eventTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50, "example": [ "order.confirmed", "ticket.issued" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } }, "paths": { "/meta/versions": { "get": { "summary": "List API versions", "operationId": "listApiVersions", "description": "Lists all dated API versions with their lifecycle status. Pin a version per-request with the TL-Version header; organisations are pinned to the version current at signup by default.", "tags": [ "Meta" ], "x-sdk-method": "versions", "x-tl-surface": "backstage", "responses": { "200": { "description": "API versions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiVersionsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/auth/login": { "post": { "summary": "User login", "operationId": "login", "description": "Authenticate a user with email and password, returns access and refresh tokens", "tags": [ "Authentication" ], "x-sdk-method": "login", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/auth/refresh": { "post": { "summary": "Refresh access token", "operationId": "refresh", "description": "Exchange a refresh token for a new access token and refresh token", "tags": [ "Authentication" ], "x-sdk-method": "refresh", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/auth/redeem": { "post": { "summary": "Redeem invitation", "operationId": "redeem", "description": "Redeem an invitation code and set up a new user account", "tags": [ "Authentication" ], "x-sdk-method": "redeem", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationRequest" } } } }, "responses": { "200": { "description": "Invitation redeemed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/auth/federate": { "post": { "summary": "Federate user to organisation", "operationId": "federate", "description": "Exchange a Stagedoor JWT token for API access and refresh tokens", "tags": [ "Authentication" ], "x-sdk-method": "federate", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederateRequest" } } } }, "responses": { "200": { "description": "Federation successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/me": { "get": { "summary": "Get current user", "operationId": "getCurrentUser", "description": "Get the currently authenticated user information", "tags": [ "Me" ], "x-sdk-method": "current", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "User retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/me/organisations": { "get": { "summary": "Get my organisations", "operationId": "getMyOrganisations", "description": "Get all organisations the current user is a member of", "tags": [ "Me" ], "x-sdk-method": "organisations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Organisations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMeOrganisationsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/me/roles": { "get": { "summary": "Get my roles", "operationId": "getMyRoles", "description": "Get the current user's role assignments with role info (name, description). Does not include permissions - use /me/permissions for that.", "tags": [ "Me" ], "x-sdk-method": "roles", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMeRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/me/permissions": { "get": { "summary": "Get my permissions", "operationId": "getMyPermissions", "description": "Get the current user's effective permissions based on their role assignments. Supports filtering by resource and/or action.", "tags": [ "Me" ], "x-sdk-method": "permissions", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "events", "description": "Filter by resource (e.g., events, accounts, orders)" }, "required": false, "description": "Filter by resource (e.g., events, accounts, orders)", "name": "resource", "in": "query" }, { "schema": { "type": "string", "example": "create", "description": "Filter by action (e.g., create, read, update, delete)" }, "required": false, "description": "Filter by action (e.g., create, read, update, delete)", "name": "action", "in": "query" } ], "responses": { "200": { "description": "Permissions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMePermissionsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/organisations/{id}": { "get": { "summary": "Get organisation", "operationId": "getOrganisation", "description": "Get organisation details including branding information", "tags": [ "Organisations" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_xyz789", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Organisation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganisationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update organisation", "operationId": "updateOrganisation", "description": "Update organisation details and branding (owner permission required)", "tags": [ "Organisations" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_xyz789", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganisationRequest" } } } }, "responses": { "200": { "description": "Organisation updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganisationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/accounts": { "get": { "summary": "List accounts", "operationId": "listAccounts", "description": "List all accounts for the organisation with optional filtering", "tags": [ "Accounts" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "Main", "description": "Search accounts by name" }, "required": false, "description": "Search accounts by name", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "inactive" ], "example": "active", "description": "Filter by account status" }, "required": false, "description": "Filter by account status", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Accounts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create account", "operationId": "createAccount", "description": "Create a new account in the organisation", "tags": [ "Accounts" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Main Account", "description": "Account name" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "example": "active", "description": "Account status" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/accounts/{id}": { "get": { "summary": "Get account", "operationId": "getAccount", "description": "Get a specific account by ID", "tags": [ "Accounts" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "acc_abc123", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAccountResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update account", "operationId": "updateAccount", "description": "Update an existing account", "tags": [ "Accounts" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "acc_abc123", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Account Name", "description": "Account name" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active", "description": "Account status" } } } } } }, "responses": { "200": { "description": "Account updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete account", "operationId": "deleteAccount", "description": "Delete an account (soft delete)", "tags": [ "Accounts" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "acc_abc123", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Account deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/identity-providers": { "get": { "summary": "List identity providers", "operationId": "listIdentityProviders", "description": "List all identity providers for the organisation", "tags": [ "Identity Providers" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123" }, "required": false, "name": "organisationId", "in": "query" } ], "responses": { "200": { "description": "Identity providers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIdentityProvidersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/identity-providers/{id}": { "get": { "summary": "Get identity provider", "operationId": "getIdentityProvider", "description": "Get a specific identity provider by ID", "tags": [ "Identity Providers" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "stagedoor-idp" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Identity provider retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetIdentityProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update identity provider", "operationId": "updateIdentityProvider", "description": "Update an identity provider configuration", "tags": [ "Identity Providers" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "stagedoor-idp" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdentityProviderRequest" } } } }, "responses": { "200": { "description": "Identity provider updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdentityProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/users/invitations": { "post": { "summary": "Create user invitation", "operationId": "createUserInvitation", "description": "Create a new user invitation and send invitation email", "tags": [ "User Invitations" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserInvitationRequest" } } } }, "responses": { "201": { "description": "Invitation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserInvitationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List user invitations", "operationId": "listUserInvitations", "description": "List all user invitations for the organisation", "tags": [ "User Invitations" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_xyz789" }, "required": false, "name": "organisationId", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "redeemed", "expired", "all" ], "example": "pending" }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Invitations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserInvitationsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/users/invitations/{id}": { "get": { "summary": "Get user invitation", "operationId": "getUserInvitation", "description": "Get a specific user invitation by ID", "tags": [ "User Invitations" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invitation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserInvitationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Cancel user invitation", "operationId": "cancelUserInvitation", "description": "Cancel a pending user invitation", "tags": [ "User Invitations" ], "x-sdk-method": "cancel", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invitation cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUserInvitationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/users/invitations/{id}/resend": { "post": { "summary": "Resend user invitation", "operationId": "resendUserInvitation", "description": "Resend a user invitation email", "tags": [ "User Invitations" ], "x-sdk-method": "resend", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invitation resent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendUserInvitationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/roles": { "get": { "summary": "List roles", "operationId": "listRoles", "description": "List all roles for the organisation. Returns both system-defined and custom roles.", "tags": [ "Roles" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Roles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create role", "operationId": "createRole", "description": "Create a new custom role with specified permissions. Permissions use format: resource.action:scope (e.g., events.create, events.read:all, events.*:acc_123)", "tags": [ "Roles" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequest" } } } }, "responses": { "201": { "description": "Role created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/roles/{id}": { "get": { "summary": "Get role", "operationId": "getRole", "description": "Get a specific role by ID", "tags": [ "Roles" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "rol_abc123", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Role retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRoleResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update role", "operationId": "updateRole", "description": "Update an existing custom role. System roles cannot be modified.", "tags": [ "Roles" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "rol_abc123", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete role", "operationId": "deleteRole", "description": "Delete a custom role (soft delete). System roles cannot be deleted.", "tags": [ "Roles" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "rol_abc123", "description": "Role ID" }, "required": true, "description": "Role ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Role deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRoleResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/user-accounts": { "get": { "summary": "List all role assignments", "operationId": "listUserAccountRoles", "description": "List all role assignments in the organisation. Shows which users have which roles on which accounts.", "tags": [ "User Account Roles" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Role assignments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserAccountRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Assign role to user", "operationId": "assignRole", "description": "Assign a role to a user for a specific account. Creates a new role assignment.", "tags": [ "User Account Roles" ], "x-sdk-method": "assign", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRoleRequest" } } } }, "responses": { "201": { "description": "Role assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRoleResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "put": { "summary": "Update user roles on account", "operationId": "updateUserAccountRoles", "description": "Update the roles for a user on an account. Replaces all existing role assignments for this user-account pair.", "tags": [ "User Account Roles" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAccountRolesRequest" } } } }, "responses": { "200": { "description": "Roles updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAccountRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/user-accounts/{id}": { "delete": { "summary": "Remove role assignment", "operationId": "removeRoleAssignment", "description": "Remove a specific role assignment from a user.", "tags": [ "User Account Roles" ], "x-sdk-method": "remove", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "uar_abc123", "description": "Role assignment ID" }, "required": true, "description": "Role assignment ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Role assignment removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAssignmentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/user-accounts/user/{userId}": { "get": { "summary": "List role assignments for user", "operationId": "listUserAccountRolesByUser", "description": "List all role assignments for a specific user across all accounts.", "tags": [ "User Account Roles" ], "x-sdk-method": "listByUser", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "usr_abc123", "description": "User ID" }, "required": true, "description": "User ID", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "Role assignments retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserAccountRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/user-accounts/account/{accountId}": { "get": { "summary": "List role assignments for account", "operationId": "listUserAccountRolesByAccount", "description": "List all role assignments for a specific account (all users with access).", "tags": [ "User Account Roles" ], "x-sdk-method": "listByAccount", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "acc_abc123", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Role assignments retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserAccountRolesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/partners/accounts": { "post": { "summary": "Provision a partner customer account", "operationId": "createPartnerAccount", "description": "For a partner server authenticated with an organisation API key (tlak_). Creates an account inside the caller's organisation, a website sales channel for it and a publishable key. Requires the accounts.write, saleschannels.write and saleschannelkeys.write scopes.", "tags": [ "Partners" ], "x-sdk-method": "createAccount", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Leander Rowing Club", "description": "Account name (the club)" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "example": "active", "description": "Account status" }, "channelName": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Leander Rowing Club website", "description": "Name of the first sales channel (defaults to \" website\")" }, "channelSlug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "example": "leander-rowing-club", "description": "Slug of the first sales channel, unique within the organisation (derived from the name when omitted)" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Account provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccountProvisioned" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/api-keys": { "post": { "summary": "Create an organisation API key", "operationId": "createApiKey", "description": "Creates a long-lived key a partner server uses to call this API and to mint embed sessions. The key material is in this response once. Users only (requires apikeys.create).", "tags": [ "API Keys" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Rowbot production", "description": "Display name for the key" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "example": [ "accounts.write", "saleschannels.write", "saleschannelkeys.write", "events.write", "orders.read" ], "description": "Scopes the key may exercise. One or more of: accounts.read, accounts.write, events.read, events.write, venues.read, venues.write, inventory.read, inventory.write, saleschannels.read, saleschannels.write, saleschannelkeys.write, orders.read, orders.write, customers.read, webhooks.read, webhooks.write" }, "accountId": { "type": "string", "minLength": 1, "example": "acc_abc123", "description": "Pin the key to one account (omit for every account in the organisation)" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "example": "2027-01-01T00:00:00Z", "description": "Optional expiry; the key stops authenticating after this instant" } }, "required": [ "name", "scopes" ] } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyCreated" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List organisation API keys", "operationId": "listApiKeys", "description": "Lists every key of the organisation, revoked ones included. Key material is never returned. Users only (requires apikeys.read).", "tags": [ "API Keys" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgApiKeysResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/api-keys/{id}": { "delete": { "summary": "Revoke an organisation API key", "operationId": "revokeApiKey", "description": "Revokes the key immediately; embed sessions it already minted run to their expiry. Users only (requires apikeys.revoke).", "tags": [ "API Keys" ], "x-sdk-method": "revoke", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "oak_abc12345" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyRevoked" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/embed/sessions": { "post": { "summary": "Mint an embed session", "operationId": "createEmbedSession", "description": "For a partner server authenticated with an organisation API key (tlak_). Mints a short-lived token pinned to one account of the key's organisation, carrying a subset of the key's scopes, for an embedded Backstage widget. User tokens and embed tokens are refused.", "tags": [ "Embed Sessions" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "example": "acc_abc123", "description": "Account the session is pinned to (must belong to the key's organisation)" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "example": [ "events.read", "orders.read" ], "description": "Subset of the API key's scopes (defaults to all of them)" }, "ttlSeconds": { "type": "integer", "minimum": 1, "maximum": 3600, "example": 900, "description": "Lifetime in seconds (default 900, max 3600)" } }, "required": [ "accountId" ] } } } }, "responses": { "201": { "description": "Embed session minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSessionCreated" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/embed/sessions/current": { "get": { "summary": "Describe the current embed session", "operationId": "getCurrentEmbedSession", "description": "For an embedded widget authenticated with an embed session token: the organisation, account, scopes and expiry of the session, so the widget can bootstrap without decoding the token.", "tags": [ "Embed Sessions" ], "x-sdk-method": "current", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Current embed session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentEmbedSession" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events": { "get": { "summary": "List events", "operationId": "listEvents", "description": "List all events for the organisation with optional filtering and pagination. Use expand=venue to embed venue details.", "tags": [ "Events" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "festival", "description": "Search events by name" }, "required": false, "description": "Search events by name", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "published", "on_sale", "sold_out", "completed", "cancelled" ], "example": "published", "description": "Filter by event status" }, "required": false, "description": "Filter by event status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "vnu_abc123", "description": "Filter by venue ID" }, "required": false, "description": "Filter by venue ID", "name": "venueId", "in": "query" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Filter by account ID" }, "required": false, "description": "Filter by account ID", "name": "accountId", "in": "query" }, { "schema": { "type": "string", "example": "venue", "description": "Comma-separated list of fields to expand. Available: venue" }, "required": false, "description": "Comma-separated list of fields to expand. Available: venue", "name": "expand", "in": "query" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Events retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create event", "operationId": "createEvent", "description": "Create a new event in the organisation", "tags": [ "Events" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID that owns this event" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Summer Music Festival", "description": "Event name" }, "subtitle": { "type": [ "string", "null" ], "maxLength": 500, "example": "Three days. Fifty artists. One field.", "description": "Short event subtitle / tagline" }, "description": { "type": "string", "example": "A three-day music festival featuring top artists", "description": "Event description" }, "shortDescription": { "type": [ "string", "null" ], "maxLength": 500, "example": "Top artists across three days.", "description": "Card / listing summary" }, "imageUrl": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "Listing / card image URL" }, "heroImageUrl": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "Event-page hero image URL" }, "presentation": { "type": [ "object", "null" ], "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hero", "cinema" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type", "size" ] }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 20 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 70 ] } ] }, "position": { "type": "string", "enum": [ "bottom", "center" ] } }, "required": [ "strength", "position" ] }, "twoColumnSplit": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] }, "navbar": { "type": "object", "properties": { "transparent": { "type": "boolean" } } }, "buttonSize": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "description": "Event-level storefront design override" }, "status": { "type": "string", "enum": [ "draft", "published", "on_sale", "sold_out", "completed", "cancelled" ], "default": "draft", "example": "draft", "description": "Event status" }, "venueId": { "type": [ "string", "null" ], "pattern": "^vnu_[a-zA-Z0-9]+$", "example": "vnu_def456", "description": "Venue ID (link to formal venue)" }, "venueName": { "type": [ "string", "null" ], "maxLength": 255, "example": "Wembley Stadium", "description": "Venue name (text-only, alternative to venueId)" }, "timezone": { "type": "string", "default": "UTC", "example": "Europe/London", "description": "Event timezone" }, "onSaleDate": { "type": "string", "format": "date-time", "example": "2025-06-01T09:00:00Z", "description": "When tickets go on sale" }, "offSaleDate": { "type": "string", "format": "date-time", "example": "2025-06-15T23:59:59Z", "description": "When sales close" }, "tags": { "type": "array", "items": { "type": "string" }, "default": [], "example": [ "music", "festival", "outdoor" ], "description": "Event tags" }, "ticketTypes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "tt_abc123", "description": "Ticket type ID (auto-generated if not provided)" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Adult", "description": "Ticket type name" }, "description": { "type": "string", "example": "Ages 16+", "description": "Ticket type description" }, "displayOrder": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order" } }, "required": [ "name", "displayOrder" ] }, "default": [], "description": "Ticket types for this event (e.g., Adult, Child)" }, "layout": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cat_abc123", "description": "Category ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Premium", "description": "Category name" }, "description": { "type": "string", "example": "Premium seating with best views", "description": "Category description" }, "displayOrder": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Display order" }, "color": { "type": "string", "example": "#3b82f6", "description": "Category colour (hex)" } }, "required": [ "name" ] }, "default": [], "description": "Pricing categories for this event" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "area_abc123", "description": "Area ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Standing", "description": "Area name" }, "description": { "type": "string", "example": "General standing area", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated", "description": "Area type (GA or allocated seating)" }, "capacity": { "type": "integer", "minimum": 0, "example": 500, "description": "Area capacity" }, "categoryId": { "type": "string", "example": "cat_abc123", "description": "Pricing category ID" }, "displayOrder": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Display order" } }, "required": [ "name", "type", "capacity" ] }, "default": [], "description": "Capacity areas (GA and/or allocated)" }, "venueLayoutTemplateId": { "type": "string", "pattern": "^vlt_[a-zA-Z0-9]+$", "example": "vlt_abc123", "description": "Source venue layout template ID (if imported)" } }, "description": "Event layout with categories and capacity areas" } }, "required": [ "accountId", "name" ] } } } }, "responses": { "201": { "description": "Event created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events/{id}": { "get": { "summary": "Get event", "operationId": "getEvent", "description": "Get a specific event by ID. Use expand=venue to embed venue details.", "tags": [ "Events" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "venue", "description": "Comma-separated list of fields to expand. Available: venue" }, "required": false, "description": "Comma-separated list of fields to expand. Available: venue", "name": "expand", "in": "query" } ], "responses": { "200": { "description": "Event retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update event", "operationId": "updateEvent", "description": "Update an existing event", "tags": [ "Events" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Festival Name", "description": "Event name" }, "subtitle": { "type": [ "string", "null" ], "maxLength": 500, "description": "Short event subtitle / tagline" }, "description": { "type": [ "string", "null" ], "example": "Updated description", "description": "Event description" }, "shortDescription": { "type": [ "string", "null" ], "maxLength": 500, "description": "Card / listing summary" }, "imageUrl": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "Listing / card image URL" }, "heroImageUrl": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "Event-page hero image URL" }, "presentation": { "type": [ "object", "null" ], "properties": { "heroLayout": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hero", "cinema" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type", "size" ] }, "cinemaGradient": { "type": "object", "properties": { "strength": { "anyOf": [ { "type": "number", "enum": [ 20 ] }, { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 70 ] } ] }, "position": { "type": "string", "enum": [ "bottom", "center" ] } }, "required": [ "strength", "position" ] }, "twoColumnSplit": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] }, "navbar": { "type": "object", "properties": { "transparent": { "type": "boolean" } } }, "buttonSize": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "description": "Event-level storefront design override" }, "status": { "type": "string", "enum": [ "draft", "published", "on_sale", "sold_out", "completed", "cancelled" ], "example": "published", "description": "Event status" }, "venueId": { "type": [ "string", "null" ], "pattern": "^vnu_[a-zA-Z0-9]+$", "example": "vnu_def456", "description": "Venue ID (link to formal venue)" }, "venueName": { "type": [ "string", "null" ], "maxLength": 255, "example": "Wembley Stadium", "description": "Venue name (text-only, alternative to venueId)" }, "timezone": { "type": "string", "example": "Europe/London", "description": "Event timezone" }, "onSaleDate": { "type": [ "string", "null" ], "format": "date-time", "example": "2025-06-01T09:00:00Z", "description": "When tickets go on sale" }, "offSaleDate": { "type": [ "string", "null" ], "format": "date-time", "example": "2025-06-15T23:59:59Z", "description": "When sales close" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "music", "festival" ], "description": "Event tags" }, "ticketTypes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "tt_abc123", "description": "Ticket type ID (auto-generated if not provided)" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Adult", "description": "Ticket type name" }, "description": { "type": "string", "example": "Ages 16+", "description": "Ticket type description" }, "displayOrder": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order" } }, "required": [ "name", "displayOrder" ] }, "description": "Ticket types for this event" }, "layout": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cat_abc123", "description": "Category ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Premium", "description": "Category name" }, "description": { "type": "string", "example": "Premium seating with best views", "description": "Category description" }, "displayOrder": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Display order" }, "color": { "type": "string", "example": "#3b82f6", "description": "Category colour (hex)" } }, "required": [ "name" ] }, "default": [], "description": "Pricing categories for this event" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "area_abc123", "description": "Area ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Standing", "description": "Area name" }, "description": { "type": "string", "example": "General standing area", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated", "description": "Area type (GA or allocated seating)" }, "capacity": { "type": "integer", "minimum": 0, "example": 500, "description": "Area capacity" }, "categoryId": { "type": "string", "example": "cat_abc123", "description": "Pricing category ID" }, "displayOrder": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Display order" } }, "required": [ "name", "type", "capacity" ] }, "default": [], "description": "Capacity areas (GA and/or allocated)" }, "venueLayoutTemplateId": { "type": "string", "pattern": "^vlt_[a-zA-Z0-9]+$", "example": "vlt_abc123", "description": "Source venue layout template ID (if imported)" } }, "description": "Event layout with categories and capacity areas" } } } } } }, "responses": { "200": { "description": "Event updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete event", "operationId": "deleteEvent", "description": "Delete an event (soft delete)", "tags": [ "Events" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Event deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events/{eventId}/occurrences": { "get": { "summary": "List occurrences for event", "operationId": "listEventOccurrences", "description": "List all occurrences for a specific event with optional filtering and pagination", "tags": [ "Event Occurrences" ], "x-sdk-method": "list", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "enum": [ "draft", "on_sale", "sold_out", "completed", "cancelled" ], "example": "on_sale", "description": "Filter by status" }, "required": false, "description": "Filter by status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "vnu_abc123", "description": "Filter by venue ID" }, "required": false, "description": "Filter by venue ID", "name": "venueId", "in": "query" }, { "schema": { "type": "string", "example": "2025-06-01T00:00:00Z", "description": "Filter occurrences starting from this date" }, "required": false, "description": "Filter occurrences starting from this date", "name": "startDateFrom", "in": "query" }, { "schema": { "type": "string", "example": "2025-06-30T23:59:59Z", "description": "Filter occurrences starting until this date" }, "required": false, "description": "Filter occurrences starting until this date", "name": "startDateTo", "in": "query" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Event occurrences retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventOccurrencesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create event occurrence", "operationId": "createEventOccurrence", "description": "Create a new occurrence for an event", "tags": [ "Event Occurrences" ], "x-sdk-method": "create", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time", "example": "2025-06-15T00:00:00Z", "description": "Start date (ISO date)" }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$", "example": "19:00:00", "description": "Start time (HH:mm:ss)" }, "endDate": { "type": "string", "format": "date-time", "example": "2025-06-15T00:00:00Z", "description": "End date (ISO date)" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$", "example": "23:00:00", "description": "End time (HH:mm:ss)" }, "timezone": { "type": "string", "default": "UTC", "example": "Europe/London", "description": "Occurrence timezone (can override event timezone)" }, "venueId": { "type": "string", "pattern": "^vnu_[a-zA-Z0-9]+$", "example": "vnu_ghi789", "description": "Venue ID (can override event venue)" }, "venueLayoutId": { "type": "string", "pattern": "^vnl_[a-zA-Z0-9]+$", "example": "vnl_jkl012", "description": "Venue layout ID" }, "ticketSchemeId": { "type": "string", "pattern": "^tsc_[a-zA-Z0-9]+$", "example": "tsc_abc123", "description": "Ticket scheme to use for this occurrence" }, "priceSchemeId": { "type": "string", "pattern": "^tps_[a-zA-Z0-9]+$", "example": "tps_def456", "description": "Price scheme to use (must belong to the ticket scheme)" }, "categoryMapping": { "type": "array", "items": { "type": "object", "properties": { "ticketCategoryId": { "type": "string", "example": "tpc_abc123", "description": "Ticket category ID from the ticket scheme" }, "venueLayoutCategoryId": { "type": "string", "example": "vlc_def456", "description": "Venue layout category ID to map to" }, "enabled": { "type": "boolean", "default": true, "example": true, "description": "Whether this category is enabled for this occurrence" } }, "required": [ "ticketCategoryId", "venueLayoutCategoryId" ] }, "description": "Category mapping for template mode ticket schemes" }, "status": { "type": "string", "enum": [ "draft", "on_sale", "sold_out", "completed", "cancelled" ], "example": "draft", "description": "Occurrence status" } }, "required": [ "startDate", "startTime", "endDate", "endTime", "status" ] } } } }, "responses": { "201": { "description": "Event occurrence created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventOccurrenceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events/{eventId}/occurrences/{occurrenceId}": { "get": { "summary": "Get event occurrence", "operationId": "getEventOccurrence", "description": "Get a specific event occurrence by ID", "tags": [ "Event Occurrences" ], "x-sdk-method": "get", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "evoc_def456", "description": "Occurrence ID" }, "required": true, "description": "Occurrence ID", "name": "occurrenceId", "in": "path" } ], "responses": { "200": { "description": "Event occurrence retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventOccurrenceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update event occurrence", "operationId": "updateEventOccurrence", "description": "Update an existing event occurrence", "tags": [ "Event Occurrences" ], "x-sdk-method": "update", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "evoc_def456", "description": "Occurrence ID" }, "required": true, "description": "Occurrence ID", "name": "occurrenceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time", "example": "2025-06-15T00:00:00Z", "description": "Start date (ISO date)" }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$", "example": "19:00:00", "description": "Start time (HH:mm:ss)" }, "endDate": { "type": "string", "format": "date-time", "example": "2025-06-15T00:00:00Z", "description": "End date (ISO date)" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$", "example": "23:00:00", "description": "End time (HH:mm:ss)" }, "timezone": { "type": "string", "example": "Europe/London", "description": "Occurrence timezone" }, "venueId": { "type": [ "string", "null" ], "pattern": "^vnu_[a-zA-Z0-9]+$", "example": "vnu_ghi789", "description": "Venue ID" }, "venueLayoutId": { "type": [ "string", "null" ], "pattern": "^vnl_[a-zA-Z0-9]+$", "example": "vnl_jkl012", "description": "Venue layout ID" }, "ticketSchemeId": { "type": [ "string", "null" ], "pattern": "^tsc_[a-zA-Z0-9]+$", "example": "tsc_abc123", "description": "Ticket scheme to use for this occurrence" }, "priceSchemeId": { "type": [ "string", "null" ], "pattern": "^tps_[a-zA-Z0-9]+$", "example": "tps_def456", "description": "Price scheme to use (must belong to the ticket scheme)" }, "categoryMapping": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "ticketCategoryId": { "type": "string", "example": "tpc_abc123", "description": "Ticket category ID from the ticket scheme" }, "venueLayoutCategoryId": { "type": "string", "example": "vlc_def456", "description": "Venue layout category ID to map to" }, "enabled": { "type": "boolean", "default": true, "example": true, "description": "Whether this category is enabled for this occurrence" } }, "required": [ "ticketCategoryId", "venueLayoutCategoryId" ] }, "description": "Category mapping for template mode ticket schemes" }, "status": { "type": "string", "enum": [ "draft", "on_sale", "sold_out", "completed", "cancelled" ], "example": "on_sale", "description": "Occurrence status" } } } } } }, "responses": { "200": { "description": "Event occurrence updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventOccurrenceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete event occurrence", "operationId": "deleteEventOccurrence", "description": "Delete an event occurrence (soft delete)", "tags": [ "Event Occurrences" ], "x-sdk-method": "delete", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "evoc_def456", "description": "Occurrence ID" }, "required": true, "description": "Occurrence ID", "name": "occurrenceId", "in": "path" } ], "responses": { "200": { "description": "Event occurrence deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEventOccurrenceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events/{eventId}/price-schemes": { "get": { "summary": "List price schemes for event", "operationId": "listEventPriceSchemes", "description": "List all price schemes for a specific event", "tags": [ "Event Price Schemes" ], "x-sdk-method": "list", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" } ], "responses": { "200": { "description": "Price schemes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPriceSchemesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create price scheme for event", "operationId": "createEventPriceScheme", "description": "Create a new price scheme for an event", "tags": [ "Event Price Schemes" ], "x-sdk-method": "create", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Standard Pricing", "description": "Price scheme name" }, "description": { "type": "string", "example": "Default pricing for all shows", "description": "Price scheme description" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "example": "draft", "description": "Price scheme status" }, "parentPriceSchemeId": { "type": "string", "example": "tps_parent123", "description": "Parent price scheme to inherit from" }, "ticketPrices": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string", "example": "cat_abc123" }, "typeId": { "type": "string", "example": "tt_def456" }, "price": { "type": "number", "minimum": 0, "example": 2500 }, "currency": { "type": "string", "enum": [ "GBP", "USD", "EUR", "AUD", "CAD" ], "default": "GBP", "example": "GBP" } }, "required": [ "categoryId", "typeId", "price" ] }, "default": [], "description": "Price matrix entries" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Price scheme created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePriceSchemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/events/{eventId}/price-schemes/{priceSchemeId}": { "get": { "summary": "Get price scheme", "operationId": "getEventPriceScheme", "description": "Get a specific price scheme by ID", "tags": [ "Event Price Schemes" ], "x-sdk-method": "get", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "tps_def456", "description": "Price scheme ID" }, "required": true, "description": "Price scheme ID", "name": "priceSchemeId", "in": "path" } ], "responses": { "200": { "description": "Price scheme retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPriceSchemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update price scheme", "operationId": "updateEventPriceScheme", "description": "Update an existing price scheme", "tags": [ "Event Price Schemes" ], "x-sdk-method": "update", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "tps_def456", "description": "Price scheme ID" }, "required": true, "description": "Price scheme ID", "name": "priceSchemeId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Pricing", "description": "Price scheme name" }, "description": { "type": [ "string", "null" ], "example": "Updated description", "description": "Price scheme description" }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "example": "active", "description": "Price scheme status" }, "ticketPrices": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string", "example": "cat_abc123" }, "typeId": { "type": "string", "example": "tt_def456" }, "price": { "type": "number", "minimum": 0, "example": 3000 }, "currency": { "type": "string", "enum": [ "GBP", "USD", "EUR", "AUD", "CAD" ], "example": "GBP" } }, "required": [ "categoryId", "typeId", "price" ] }, "description": "Price matrix entries" } } } } } }, "responses": { "200": { "description": "Price scheme updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePriceSchemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete price scheme", "operationId": "deleteEventPriceScheme", "description": "Delete a price scheme (soft delete)", "tags": [ "Event Price Schemes" ], "x-sdk-method": "delete", "x-parent-resource": "Events", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "Event ID" }, "required": true, "description": "Event ID", "name": "eventId", "in": "path" }, { "schema": { "type": "string", "example": "tps_def456", "description": "Price scheme ID" }, "required": true, "description": "Price scheme ID", "name": "priceSchemeId", "in": "path" } ], "responses": { "200": { "description": "Price scheme deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePriceSchemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues": { "get": { "summary": "List venues", "operationId": "listVenues", "description": "List all venues for the organisation with optional filtering and pagination", "tags": [ "Venues" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "royal", "description": "Search venues by name" }, "required": false, "description": "Search venues by name", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "archived" ], "example": "active", "description": "Filter by venue status" }, "required": false, "description": "Filter by venue status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Filter by account ID" }, "required": false, "description": "Filter by account ID", "name": "accountId", "in": "query" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Venues retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVenuesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create venue", "operationId": "createVenue", "description": "Create a new venue in the organisation", "tags": [ "Venues" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID that owns this venue" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Royal Albert Hall", "description": "Venue name" }, "description": { "type": "string", "example": "Historic concert hall in London", "description": "Venue description" }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active", "example": "active", "description": "Venue status" }, "streetAddress": { "type": "string", "example": "Kensington Gore", "description": "Street address" }, "city": { "type": "string", "example": "London", "description": "City" }, "country": { "type": "string", "example": "United Kingdom", "description": "Country" }, "coordinates": { "type": "object", "properties": { "longitude": { "type": "number", "minimum": -180, "maximum": 180, "example": -0.1278, "description": "Longitude (-180 to 180)" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "example": 51.5074, "description": "Latitude (-90 to 90)" } }, "required": [ "longitude", "latitude" ], "description": "GPS coordinates for mapping" }, "timezone": { "type": "string", "default": "UTC", "example": "Europe/London", "description": "IANA timezone" }, "phone": { "type": "string", "example": "+44 20 7589 8212", "description": "Contact phone number" }, "email": { "type": "string", "format": "email", "example": "info@royalalberthall.com", "description": "Contact email" }, "website": { "type": "string", "format": "uri", "example": "https://www.royalalberthall.com", "description": "Venue website" }, "features": { "type": "array", "items": { "type": "string" }, "default": [], "example": [ "parking", "wheelchair_accessible", "bar", "restaurant" ], "description": "Venue features and facilities" }, "tags": { "type": "array", "items": { "type": "string" }, "default": [], "example": [ "concert-hall", "historic", "premium" ], "description": "Venue tags" } }, "required": [ "accountId", "name" ] } } } }, "responses": { "201": { "description": "Venue created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVenueResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}": { "get": { "summary": "Get venue", "operationId": "getVenue", "description": "Get a specific venue by ID", "tags": [ "Venues" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Venue retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVenueResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update venue", "operationId": "updateVenue", "description": "Update an existing venue", "tags": [ "Venues" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Venue Name", "description": "Venue name" }, "description": { "type": "string", "example": "Updated description", "description": "Venue description" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active", "description": "Venue status" }, "streetAddress": { "type": "string", "example": "Updated Street", "description": "Street address" }, "city": { "type": "string", "example": "London", "description": "City" }, "country": { "type": "string", "example": "United Kingdom", "description": "Country" }, "coordinates": { "type": [ "object", "null" ], "properties": { "longitude": { "type": "number", "minimum": -180, "maximum": 180, "example": -0.1278, "description": "Longitude (-180 to 180)" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "example": 51.5074, "description": "Latitude (-90 to 90)" } }, "required": [ "longitude", "latitude" ], "description": "GPS coordinates for mapping" }, "timezone": { "type": "string", "example": "Europe/London", "description": "IANA timezone" }, "phone": { "type": [ "string", "null" ], "example": "+44 20 7589 8212", "description": "Contact phone number" }, "email": { "type": [ "string", "null" ], "format": "email", "example": "info@venue.com", "description": "Contact email" }, "website": { "type": [ "string", "null" ], "format": "uri", "example": "https://www.venue.com", "description": "Venue website" }, "features": { "type": "array", "items": { "type": "string" }, "example": [ "parking", "wheelchair_accessible" ], "description": "Venue features and facilities" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "concert-hall", "historic" ], "description": "Venue tags" } } } } } }, "responses": { "200": { "description": "Venue updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVenueResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete venue", "operationId": "deleteVenue", "description": "Delete a venue (soft delete)", "tags": [ "Venues" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Venue deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVenueResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts": { "get": { "summary": "List layouts for venue", "operationId": "listVenueLayouts", "description": "List all layouts for a specific venue with optional filtering and pagination", "tags": [ "Venue Layouts" ], "x-sdk-method": "list", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "theatre", "description": "Search layouts by name" }, "required": false, "description": "Search layouts by name", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "archived" ], "example": "active", "description": "Filter by layout status" }, "required": false, "description": "Filter by layout status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Filter by account ID" }, "required": false, "description": "Filter by account ID", "name": "accountId", "in": "query" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Venue layouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVenueLayoutsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create venue layout", "operationId": "createVenueLayout", "description": "Create a new layout for a venue", "tags": [ "Venue Layouts" ], "x-sdk-method": "create", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Theatre Mode", "description": "Layout name" }, "description": { "type": "string", "example": "Standard theatre configuration with allocated seating", "description": "Layout description" }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active", "example": "active", "description": "Layout status" }, "totalCapacity": { "type": "number", "minimum": 0, "default": 0, "example": 1500, "description": "Total capacity (denormalized sum of all area capacities)" }, "floors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlf_ground", "description": "Floor ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Ground Floor", "description": "Floor name" }, "displayOrder": { "type": "number", "example": 0, "description": "Display order (0 = ground, higher = upper floors)" }, "description": { "type": "string", "example": "Main entrance level", "description": "Floor description" } }, "required": [ "name", "displayOrder" ] }, "default": [], "description": "Floors for multi-level venues" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlc_premium", "description": "Category ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Premium", "description": "Category name" }, "description": { "type": "string", "example": "Best seats in the house", "description": "Category description" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" } }, "required": [ "name", "displayOrder" ] }, "default": [], "description": "Pricing categories/zones" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vla_main", "description": "Area ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Main Floor", "description": "Area name" }, "description": { "type": "string", "example": "General admission standing area", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated", "description": "Area type (unallocated = GA, allocated = assigned seating)" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "example": "active" }, "floorId": { "type": "string", "example": "vlf_ground", "description": "Floor ID (for multi-level venues)" }, "capacity": { "type": "number", "minimum": 0, "example": 500, "description": "Total capacity" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vls_left", "description": "Section ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Left", "description": "Section name" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "description": { "type": "string", "example": "Stage left section", "description": "Section description" } }, "required": [ "name", "displayOrder" ] }, "description": "Optional subdivisions within the area" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 0, "description": "X coordinate" }, "y": { "type": "number", "example": 0, "description": "Y coordinate" }, "width": { "type": "number", "example": 200, "description": "Width of area" }, "height": { "type": "number", "example": 150, "description": "Height of area" } }, "required": [ "x", "y", "width", "height" ], "description": "Visual positioning for GA areas on map" }, "seats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlas_xyz", "description": "Seat ID (auto-generated if not provided)" }, "sectionId": { "type": "string", "example": "vls_left", "description": "Section ID within the area" }, "section": { "type": "string", "example": "Orchestra", "description": "Legacy/display section name" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra, Row A, Seat 15", "description": "Display label" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "default": "available", "example": "available" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "default": [], "example": [ "aisle_left", "excellent_view" ] }, "companionSeats": { "type": "array", "items": { "type": "string" }, "example": [ "vlas_abc", "vlas_def" ], "description": "Related companion seat IDs" }, "companionTo": { "type": "string", "example": "vlas_wheelchair", "description": "Wheelchair space this is companion to" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100, "description": "X coordinate" }, "y": { "type": "number", "example": 200, "description": "Y coordinate" }, "rotation": { "type": "number", "minimum": 0, "maximum": 359, "example": 0, "description": "Rotation in degrees (0-359)" } }, "required": [ "x", "y" ], "description": "Visual positioning for seat maps" }, "internalNotes": { "type": "string", "example": "Next to sound booth", "description": "Internal notes" }, "publicNotes": { "type": "string", "example": "Limited view of stage left", "description": "Public-facing notes" } }, "required": [ "row", "number", "label" ] }, "description": "Seats array (only for allocated seating areas)" } }, "required": [ "name", "type", "capacity", "displayOrder" ] }, "default": [], "description": "Venue areas (GA and allocated)" }, "decorations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vld_stage1", "description": "Decoration ID (auto-generated if not provided)" }, "type": { "type": "string", "enum": [ "stage", "pillar", "barrier", "aisle", "wall", "exit", "entrance", "bar", "restroom", "label", "custom" ], "example": "stage", "description": "Decoration type" }, "name": { "type": "string", "example": "Main Stage", "description": "Decoration name" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100, "description": "X coordinate" }, "y": { "type": "number", "example": 200, "description": "Y coordinate" }, "width": { "type": "number", "example": 300, "description": "Width" }, "height": { "type": "number", "example": 80, "description": "Height" }, "rotation": { "type": "number", "example": 0, "description": "Rotation in degrees" } }, "required": [ "x", "y", "width", "height" ], "description": "Position and dimensions" }, "label": { "type": "string", "example": "STAGE", "description": "Display label text" }, "style": { "type": "object", "properties": { "fill": { "type": "string", "example": "#666666", "description": "Fill colour" }, "stroke": { "type": "string", "example": "#333333", "description": "Stroke colour" }, "fontSize": { "type": "number", "example": 14, "description": "Font size for labels" }, "fontWeight": { "type": "string", "example": "bold", "description": "Font weight for labels" } }, "description": "Visual styling" } }, "required": [ "type", "position" ] }, "default": [], "description": "Visual elements (stages, pillars, labels, etc.)" }, "tags": { "type": "array", "items": { "type": "string" }, "default": [], "example": [ "theatre", "seated" ], "description": "Layout tags" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Venue layout created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVenueLayoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}": { "get": { "summary": "Get venue layout", "operationId": "getVenueLayout", "description": "Get a specific venue layout by ID", "tags": [ "Venue Layouts" ], "x-sdk-method": "get", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" } ], "responses": { "200": { "description": "Venue layout retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVenueLayoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update venue layout", "operationId": "updateVenueLayout", "description": "Update an existing venue layout", "tags": [ "Venue Layouts" ], "x-sdk-method": "update", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Theatre Mode", "description": "Layout name" }, "description": { "type": "string", "example": "Updated description", "description": "Layout description" }, "status": { "type": "string", "enum": [ "active", "archived" ], "example": "active", "description": "Layout status" }, "totalCapacity": { "type": "number", "minimum": 0, "example": 1600, "description": "Total capacity" }, "floors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlf_ground", "description": "Floor ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Ground Floor", "description": "Floor name" }, "displayOrder": { "type": "number", "example": 0, "description": "Display order (0 = ground, higher = upper floors)" }, "description": { "type": "string", "example": "Main entrance level", "description": "Floor description" } }, "required": [ "name", "displayOrder" ] }, "description": "Floors for multi-level venues" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlc_premium", "description": "Category ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Premium", "description": "Category name" }, "description": { "type": "string", "example": "Best seats in the house", "description": "Category description" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" } }, "required": [ "name", "displayOrder" ] }, "description": "Pricing categories/zones" }, "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vla_main", "description": "Area ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Main Floor", "description": "Area name" }, "description": { "type": "string", "example": "General admission standing area", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated", "description": "Area type (unallocated = GA, allocated = assigned seating)" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "example": "active" }, "floorId": { "type": "string", "example": "vlf_ground", "description": "Floor ID (for multi-level venues)" }, "capacity": { "type": "number", "minimum": 0, "example": 500, "description": "Total capacity" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vls_left", "description": "Section ID (auto-generated if not provided)" }, "name": { "type": "string", "example": "Left", "description": "Section name" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI" }, "description": { "type": "string", "example": "Stage left section", "description": "Section description" } }, "required": [ "name", "displayOrder" ] }, "description": "Optional subdivisions within the area" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 0, "description": "X coordinate" }, "y": { "type": "number", "example": 0, "description": "Y coordinate" }, "width": { "type": "number", "example": 200, "description": "Width of area" }, "height": { "type": "number", "example": 150, "description": "Height of area" } }, "required": [ "x", "y", "width", "height" ], "description": "Visual positioning for GA areas on map" }, "seats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlas_xyz", "description": "Seat ID (auto-generated if not provided)" }, "sectionId": { "type": "string", "example": "vls_left", "description": "Section ID within the area" }, "section": { "type": "string", "example": "Orchestra", "description": "Legacy/display section name" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra, Row A, Seat 15", "description": "Display label" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "default": "available", "example": "available" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "default": [], "example": [ "aisle_left", "excellent_view" ] }, "companionSeats": { "type": "array", "items": { "type": "string" }, "example": [ "vlas_abc", "vlas_def" ], "description": "Related companion seat IDs" }, "companionTo": { "type": "string", "example": "vlas_wheelchair", "description": "Wheelchair space this is companion to" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100, "description": "X coordinate" }, "y": { "type": "number", "example": 200, "description": "Y coordinate" }, "rotation": { "type": "number", "minimum": 0, "maximum": 359, "example": 0, "description": "Rotation in degrees (0-359)" } }, "required": [ "x", "y" ], "description": "Visual positioning for seat maps" }, "internalNotes": { "type": "string", "example": "Next to sound booth", "description": "Internal notes" }, "publicNotes": { "type": "string", "example": "Limited view of stage left", "description": "Public-facing notes" } }, "required": [ "row", "number", "label" ] }, "description": "Seats array (only for allocated seating areas)" } }, "required": [ "name", "type", "capacity", "displayOrder" ] }, "description": "Venue areas (GA and allocated)" }, "decorations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vld_stage1", "description": "Decoration ID (auto-generated if not provided)" }, "type": { "type": "string", "enum": [ "stage", "pillar", "barrier", "aisle", "wall", "exit", "entrance", "bar", "restroom", "label", "custom" ], "example": "stage", "description": "Decoration type" }, "name": { "type": "string", "example": "Main Stage", "description": "Decoration name" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100, "description": "X coordinate" }, "y": { "type": "number", "example": 200, "description": "Y coordinate" }, "width": { "type": "number", "example": 300, "description": "Width" }, "height": { "type": "number", "example": 80, "description": "Height" }, "rotation": { "type": "number", "example": 0, "description": "Rotation in degrees" } }, "required": [ "x", "y", "width", "height" ], "description": "Position and dimensions" }, "label": { "type": "string", "example": "STAGE", "description": "Display label text" }, "style": { "type": "object", "properties": { "fill": { "type": "string", "example": "#666666", "description": "Fill colour" }, "stroke": { "type": "string", "example": "#333333", "description": "Stroke colour" }, "fontSize": { "type": "number", "example": 14, "description": "Font size for labels" }, "fontWeight": { "type": "string", "example": "bold", "description": "Font weight for labels" } }, "description": "Visual styling" } }, "required": [ "type", "position" ] }, "description": "Visual elements (stages, pillars, labels, etc.)" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "theatre", "seated", "accessible" ], "description": "Layout tags" } } } } } }, "responses": { "200": { "description": "Venue layout updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVenueLayoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete venue layout", "operationId": "deleteVenueLayout", "description": "Delete a venue layout (soft delete)", "tags": [ "Venue Layouts" ], "x-sdk-method": "delete", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" } ], "responses": { "200": { "description": "Venue layout deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVenueLayoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas": { "post": { "summary": "Add area to venue layout", "operationId": "addAreaToVenueLayout", "description": "Add a new area to a venue layout", "tags": [ "Venue Layout Areas" ], "x-sdk-method": "addArea", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Main Floor", "description": "Area name" }, "description": { "type": "string", "example": "General admission standing area", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "unallocated", "description": "Area type (unallocated for GA, allocated for assigned seating)" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "example": "active", "description": "Area status" }, "capacity": { "type": "number", "minimum": 0, "example": 500, "description": "Total capacity for this area" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI (auto-assigned if not provided)" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" }, "seats": { "type": "array", "items": {}, "description": "Seats array (only for allocated seating areas, leave empty for GA)" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "example": { "x": 100, "y": 100, "width": 200, "height": 150 }, "description": "Visual positioning for GA areas on seating map" }, "categoryId": { "type": "string", "pattern": "^vlc_[a-zA-Z0-9]+$", "example": "vlc_abc123", "description": "Category ID for pricing (especially for GA areas)" } }, "required": [ "name", "type", "capacity" ] } } } }, "responses": { "201": { "description": "Area added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAreaResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}": { "patch": { "summary": "Update venue layout area", "operationId": "updateVenueLayoutArea", "description": "Update an area in a venue layout", "tags": [ "Venue Layout Areas" ], "x-sdk-method": "updateArea", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Main Floor", "description": "Area name" }, "description": { "type": "string", "example": "Updated description", "description": "Area description" }, "type": { "type": "string", "enum": [ "unallocated", "allocated" ], "example": "allocated", "description": "Area type" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "inactive", "description": "Area status" }, "capacity": { "type": "number", "minimum": 0, "example": 600, "description": "Total capacity" }, "displayOrder": { "type": "number", "example": 2, "description": "Display order in UI" }, "color": { "type": "string", "example": "#FF0000", "description": "Hex color" }, "seats": { "type": "array", "items": {}, "description": "Seats array" }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "example": { "x": 100, "y": 100, "width": 200, "height": 150 }, "description": "Visual positioning for GA areas on seating map" }, "categoryId": { "type": "string", "pattern": "^vlc_[a-zA-Z0-9]+$", "example": "vlc_abc123", "description": "Category ID for pricing (especially for GA areas)" } } } } } }, "responses": { "200": { "description": "Area updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAreaResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete venue layout area", "operationId": "deleteVenueLayoutArea", "description": "Delete an area from a venue layout", "tags": [ "Venue Layout Areas" ], "x-sdk-method": "deleteArea", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "responses": { "200": { "description": "Area deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAreaResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/categories": { "post": { "summary": "Add category to venue layout", "operationId": "addCategoryToVenueLayout", "description": "Add a new pricing category to a venue layout", "tags": [ "Venue Layout Categories" ], "x-sdk-method": "addCategory", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Premium", "description": "Category name (e.g., Premium, Standard, VIP)" }, "description": { "type": "string", "example": "Best seats in the house with excellent sightlines", "description": "Category description" }, "displayOrder": { "type": "number", "example": 1, "description": "Display order in UI (auto-assigned if not provided)" }, "color": { "type": "string", "example": "#FFD700", "description": "Hex color for visual distinction" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Category added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCategoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/categories/{categoryId}": { "patch": { "summary": "Update venue layout category", "operationId": "updateVenueLayoutCategory", "description": "Update a pricing category in a venue layout", "tags": [ "Venue Layout Categories" ], "x-sdk-method": "updateCategory", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vlc_ghi789", "description": "Category ID" }, "required": true, "description": "Category ID", "name": "categoryId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "VIP Premium", "description": "Category name" }, "description": { "type": "string", "example": "Updated description", "description": "Category description" }, "displayOrder": { "type": "number", "example": 2, "description": "Display order in UI" }, "color": { "type": "string", "example": "#C0C0C0", "description": "Hex color" } } } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCategoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete venue layout category", "operationId": "deleteVenueLayoutCategory", "description": "Delete a pricing category from a venue layout", "tags": [ "Venue Layout Categories" ], "x-sdk-method": "deleteCategory", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vlc_ghi789", "description": "Category ID" }, "required": true, "description": "Category ID", "name": "categoryId", "in": "path" } ], "responses": { "200": { "description": "Category deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCategoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}/seats": { "post": { "summary": "Add seat to area", "operationId": "addSeatToArea", "description": "Add a single seat to an allocated seating area", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "addSeat", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string", "example": "Orchestra Center", "description": "Section identifier" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra Center, Row A, Seat 15", "description": "Display label (auto-generated if not provided)" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID for pricing" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "example": "available", "description": "Seat status" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "example": [ "aisle_right", "excellent_view" ], "description": "Seat attributes" }, "companionSeats": { "type": "array", "items": { "type": "string" }, "example": [ "vlas_h9", "vlas_h10" ], "description": "IDs of companion seats (for wheelchair spaces)" }, "companionTo": { "type": "string", "example": "vlas_h8", "description": "ID of wheelchair space this is companion to" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100.5, "description": "X coordinate on map" }, "y": { "type": "number", "example": 200.5, "description": "Y coordinate on map" }, "rotation": { "type": "number", "example": 0, "description": "0-359 degrees" } }, "required": [ "x", "y" ] }, "internalNotes": { "type": "string", "example": "Next to sound booth", "description": "Internal notes" }, "publicNotes": { "type": "string", "example": "Best view of stage", "description": "Public notes shown to customers" } }, "required": [ "row", "number" ] } } } }, "responses": { "201": { "description": "Seat added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSeatResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}/seats/bulk": { "post": { "summary": "Bulk add seats to area", "operationId": "bulkAddSeatsToArea", "description": "Add multiple seats to an allocated seating area at once", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "bulkAddSeats", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string", "example": "Orchestra Center", "description": "Section identifier" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra Center, Row A, Seat 15", "description": "Display label (auto-generated if not provided)" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID for pricing" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "example": "available", "description": "Seat status" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "example": [ "aisle_right", "excellent_view" ], "description": "Seat attributes" }, "companionSeats": { "type": "array", "items": { "type": "string" }, "example": [ "vlas_h9", "vlas_h10" ], "description": "IDs of companion seats (for wheelchair spaces)" }, "companionTo": { "type": "string", "example": "vlas_h8", "description": "ID of wheelchair space this is companion to" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100.5, "description": "X coordinate on map" }, "y": { "type": "number", "example": 200.5, "description": "Y coordinate on map" }, "rotation": { "type": "number", "example": 0, "description": "0-359 degrees" } }, "required": [ "x", "y" ] }, "internalNotes": { "type": "string", "example": "Next to sound booth", "description": "Internal notes" }, "publicNotes": { "type": "string", "example": "Best view of stage", "description": "Public notes shown to customers" } }, "required": [ "row", "number" ] }, "description": "Array of seats to add" } }, "required": [ "seats" ] } } } }, "responses": { "201": { "description": "Seats added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAddSeatsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}/seats/generate": { "post": { "summary": "Generate seats for area", "operationId": "generateSeatsForArea", "description": "Generate seats from a template specifying rows and seats per row", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "generateSeats", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string", "example": "Orchestra", "description": "Section name for all generated seats" }, "startRow": { "type": "string", "example": "A", "description": "Starting row (can be letter A-Z or number)" }, "endRow": { "type": "string", "example": "J", "description": "Ending row (can be letter A-Z or number)" }, "seatsPerRow": { "type": "number", "minimum": 1, "maximum": 200, "example": 20, "description": "Number of seats per row" }, "rowPrefix": { "type": "string", "example": "R", "description": "Prefix for row labels" }, "seatPrefix": { "type": "string", "example": "", "description": "Prefix for seat numbers" }, "categoryId": { "type": "string", "example": "vlc_standard", "description": "Category ID for all generated seats" }, "skipRows": { "type": "array", "items": { "type": "string" }, "example": [ "C", "F" ], "description": "Rows to skip" }, "skipSeats": { "type": "array", "items": { "type": "string" }, "example": [ "A-1", "A-2" ], "description": "Specific seats to skip (format: row-seat)" } }, "required": [ "startRow", "endRow", "seatsPerRow" ] } } } }, "responses": { "201": { "description": "Seats generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSeatsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}/seats/sync": { "put": { "summary": "Sync seats in area", "operationId": "syncSeatsInArea", "description": "Replace all seats in an allocated seating area with the provided seats. Used by the visual seating map editor for full saves.", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "syncSeats", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "vlas_xyz789", "description": "Existing seat ID (if updating) or temporary editor ID" }, "section": { "type": "string", "example": "Orchestra Center", "description": "Section identifier" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra Center, Row A, Seat 15", "description": "Display label" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID for pricing" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "example": "available", "description": "Seat status" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "example": [ "aisle_right" ], "description": "Seat attributes" }, "companionSeats": { "type": "array", "items": { "type": "string" } }, "companionTo": { "type": "string" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100.5, "description": "X coordinate on map" }, "y": { "type": "number", "example": 200.5, "description": "Y coordinate on map" }, "rotation": { "type": "number", "example": 0, "description": "0-359 degrees" } }, "required": [ "x", "y" ] }, "internalNotes": { "type": "string" }, "publicNotes": { "type": "string" } }, "required": [ "row", "number" ] }, "description": "Array of seats to sync" }, "clearExisting": { "type": "boolean", "default": true, "example": true, "description": "Whether to clear existing seats before syncing (default: true)" } }, "required": [ "seats" ] } } } }, "responses": { "200": { "description": "Seats synced successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSeatsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/venues/{id}/layouts/{layoutId}/areas/{areaId}/seats/{seatId}": { "patch": { "summary": "Update seat in area", "operationId": "updateSeatInArea", "description": "Update a seat in an allocated seating area", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "updateSeat", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" }, { "schema": { "type": "string", "example": "vlas_jkl012", "description": "Seat ID" }, "required": true, "description": "Seat ID", "name": "seatId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string", "example": "Orchestra Center", "description": "Section identifier" }, "row": { "type": "string", "example": "A", "description": "Row identifier" }, "number": { "type": "string", "example": "15", "description": "Seat number" }, "label": { "type": "string", "example": "Orchestra Center, Row A, Seat 15", "description": "Display label (auto-generated if not provided)" }, "categoryId": { "type": "string", "example": "vlc_premium", "description": "Category ID for pricing" }, "status": { "type": "string", "enum": [ "available", "blocked", "accessible", "held", "removed" ], "example": "available", "description": "Seat status" }, "holdType": { "type": "string", "example": "promoter", "description": "Hold type if status is held" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "aisle_left", "aisle_right", "accessible", "wheelchair_space", "companion_seat", "easy_access", "obstructed_view", "restricted_view", "excellent_view", "stage_view", "extra_legroom", "premium_comfort", "front_row", "back_row", "center" ] }, "example": [ "aisle_right", "excellent_view" ], "description": "Seat attributes" }, "companionSeats": { "type": "array", "items": { "type": "string" }, "example": [ "vlas_h9", "vlas_h10" ], "description": "IDs of companion seats (for wheelchair spaces)" }, "companionTo": { "type": "string", "example": "vlas_h8", "description": "ID of wheelchair space this is companion to" }, "position": { "type": "object", "properties": { "x": { "type": "number", "example": 100.5, "description": "X coordinate on map" }, "y": { "type": "number", "example": 200.5, "description": "Y coordinate on map" }, "rotation": { "type": "number", "example": 0, "description": "0-359 degrees" } }, "required": [ "x", "y" ] }, "internalNotes": { "type": "string", "example": "Next to sound booth", "description": "Internal notes" }, "publicNotes": { "type": "string", "example": "Best view of stage", "description": "Public notes shown to customers" } } } } } }, "responses": { "200": { "description": "Seat updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSeatResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete seat from area", "operationId": "deleteSeatFromArea", "description": "Delete a seat from an allocated seating area", "tags": [ "Venue Layout Seats" ], "x-sdk-method": "deleteSeat", "x-parent-resource": "Venues", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "vnu_abc123", "description": "Venue ID" }, "required": true, "description": "Venue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "vnl_def456", "description": "Layout ID" }, "required": true, "description": "Layout ID", "name": "layoutId", "in": "path" }, { "schema": { "type": "string", "example": "vla_ghi789", "description": "Area ID" }, "required": true, "description": "Area ID", "name": "areaId", "in": "path" }, { "schema": { "type": "string", "example": "vlas_jkl012", "description": "Seat ID" }, "required": true, "description": "Seat ID", "name": "seatId", "in": "path" } ], "responses": { "200": { "description": "Seat deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSeatResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/packages": { "get": { "summary": "List credit packages", "operationId": "listCreditPackages", "description": "List all available credit packages for purchase", "tags": [ "Billing" ], "x-sdk-method": "listPackages", "x-tl-surface": "backstage", "responses": { "200": { "description": "Credit packages retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPackagesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/organisations/{organisationId}/billing/can-sell": { "get": { "summary": "Check if organisation can sell", "operationId": "checkCanSell", "description": "Check if an organisation has sufficient credits to process sales", "tags": [ "Billing" ], "x-sdk-method": "canSell", "x-tl-surface": "backstage", "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "responses": { "200": { "description": "Can sell status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanSellResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/balance": { "get": { "summary": "Get credit balance", "operationId": "getCreditBalance", "description": "Get the current credit balance for an organisation", "tags": [ "Billing" ], "x-sdk-method": "getBalance", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "responses": { "200": { "description": "Credit balance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBalanceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/transactions": { "get": { "summary": "List credit transactions", "operationId": "listCreditTransactions", "description": "List all credit transactions for an organisation", "tags": [ "Billing" ], "x-sdk-method": "listTransactions", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "50", "description": "Items per page" }, "required": false, "description": "Items per page", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "purchase", "description": "Filter by transaction type" }, "required": false, "description": "Filter by transaction type", "name": "type", "in": "query" } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTransactionsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/purchases": { "post": { "summary": "Purchase credits", "operationId": "createCreditPurchase", "description": "Purchase a credit package for an organisation", "tags": [ "Billing" ], "x-sdk-method": "createPurchase", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePurchaseRequest" } } } }, "responses": { "201": { "description": "Purchase completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResult" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/invoices": { "get": { "summary": "List invoices", "operationId": "listInvoices", "description": "List all invoices for an organisation", "tags": [ "Billing" ], "x-sdk-method": "listInvoices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "50", "description": "Items per page" }, "required": false, "description": "Items per page", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "paid", "description": "Filter by invoice status" }, "required": false, "description": "Filter by invoice status", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Invoices retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInvoicesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/invoices/{invoiceId}": { "get": { "summary": "Get invoice", "operationId": "getInvoice", "description": "Get a specific invoice by ID", "tags": [ "Billing" ], "x-sdk-method": "getInvoice", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" }, { "schema": { "type": "string", "example": "inv_abc123", "description": "Invoice ID" }, "required": true, "description": "Invoice ID", "name": "invoiceId", "in": "path" } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInvoiceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/payments": { "get": { "summary": "List billing payments", "operationId": "listBillingPayments", "description": "List all billing payments for an organisation", "tags": [ "Billing" ], "x-sdk-method": "listPayments", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" }, { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "50", "description": "Items per page" }, "required": false, "description": "Items per page", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "succeeded", "description": "Filter by payment status" }, "required": false, "description": "Filter by payment status", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaymentsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/subscriptions": { "post": { "summary": "Create subscription", "operationId": "createSubscription", "description": "Create a new credit subscription for an organisation", "tags": [ "Billing" ], "x-sdk-method": "createSubscription", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "Subscription created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List subscriptions", "operationId": "listSubscriptions", "description": "List all subscriptions for an organisation", "tags": [ "Billing" ], "x-sdk-method": "listSubscriptions", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "responses": { "200": { "description": "Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/subscriptions/{subscriptionId}": { "delete": { "summary": "Cancel subscription", "operationId": "cancelSubscription", "description": "Cancel an active subscription", "tags": [ "Billing" ], "x-sdk-method": "cancelSubscription", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" }, { "schema": { "type": "string", "example": "sub_abc123", "description": "Subscription ID" }, "required": true, "description": "Subscription ID", "name": "subscriptionId", "in": "path" } ], "responses": { "200": { "description": "Subscription cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/auto-topup": { "get": { "summary": "Get auto top-up configuration", "operationId": "getAutoTopup", "description": "Get the auto top-up configuration for an organisation", "tags": [ "Billing" ], "x-sdk-method": "getAutoTopup", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "responses": { "200": { "description": "Auto top-up configuration retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAutoTopupResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "put": { "summary": "Update auto top-up configuration", "operationId": "updateAutoTopup", "description": "Update the auto top-up configuration for an organisation", "tags": [ "Billing" ], "x-sdk-method": "updateAutoTopup", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "org_abc123", "description": "Organisation ID" }, "required": true, "description": "Organisation ID", "name": "organisationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoTopupRequest" } } } }, "responses": { "200": { "description": "Auto top-up configuration updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoTopupResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/payment-methods": { "get": { "summary": "List payment methods", "operationId": "listPaymentMethods", "description": "List all saved payment methods for the organisation", "tags": [ "Billing" ], "x-sdk-method": "listPaymentMethods", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Payment methods retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaymentMethodsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Save payment method", "operationId": "savePaymentMethod", "description": "Save a payment method after Stripe confirms the setup intent", "tags": [ "Billing" ], "x-sdk-method": "savePaymentMethod", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavePaymentMethodRequest" } } } }, "responses": { "201": { "description": "Payment method saved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavePaymentMethodResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/setup-intent": { "post": { "summary": "Create setup intent", "operationId": "createSetupIntent", "description": "Create a Stripe setup intent for saving a new payment method", "tags": [ "Billing" ], "x-sdk-method": "createSetupIntent", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "201": { "description": "Setup intent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSetupIntentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/payment-methods/{paymentMethodId}": { "delete": { "summary": "Delete payment method", "operationId": "deletePaymentMethod", "description": "Delete a saved payment method", "tags": [ "Billing" ], "x-sdk-method": "deletePaymentMethod", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "pm_1234567890", "description": "Payment method ID" }, "required": true, "description": "Payment method ID", "name": "paymentMethodId", "in": "path" } ], "responses": { "200": { "description": "Payment method deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePaymentMethodResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/payment-methods/{paymentMethodId}/default": { "put": { "summary": "Set default payment method", "operationId": "setDefaultPaymentMethod", "description": "Set a payment method as the default for the organisation", "tags": [ "Billing" ], "x-sdk-method": "setDefaultPaymentMethod", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "pm_1234567890", "description": "Payment method ID" }, "required": true, "description": "Payment method ID", "name": "paymentMethodId", "in": "path" } ], "responses": { "200": { "description": "Default payment method set successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultPaymentMethodResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/ai/packages": { "get": { "summary": "List AI credit packages", "operationId": "listAiCreditPackages", "description": "List the AI-credit top-up packages available for purchase", "tags": [ "Billing" ], "x-sdk-method": "listAiPackages", "x-tl-surface": "backstage", "responses": { "200": { "description": "AI credit packages retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiPackagesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/ai/balance": { "get": { "summary": "Get AI credit balance", "operationId": "getAiBalance", "description": "Get the organisation's AI-credit (Cue) wallet balance", "tags": [ "Billing" ], "x-sdk-method": "getAiBalance", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "AI balance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAiBalanceResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/ai/transactions": { "get": { "summary": "List AI credit transactions", "operationId": "listAiCreditTransactions", "description": "List the AI-credit wallet transaction history", "tags": [ "Billing" ], "x-sdk-method": "listAiTransactions", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "example": "50", "description": "Items per page" }, "required": false, "description": "Items per page", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "AI transactions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTransactionsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/billing/ai-topup": { "post": { "summary": "Top up AI credits", "operationId": "createAiTopup", "description": "Purchase AI credits directly (separate from the bundle included with ticket-credit purchases)", "tags": [ "Billing" ], "x-sdk-method": "createAiTopup", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiTopupRequest" } } } }, "responses": { "201": { "description": "AI credit top-up completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiTopupResult" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory": { "post": { "summary": "Create inventory", "operationId": "createInventory", "description": "Create a new inventory bucket for tracking capacity", "tags": [ "Inventory" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceType": { "type": "string", "enum": [ "event_occurrence_area", "product" ], "example": "event_occurrence_area", "description": "Type of inventory source" }, "eventId": { "type": "string", "example": "evt_abc123", "description": "Event ID (required for event_occurrence_area)" }, "eventOccurrenceId": { "type": "string", "example": "evo_abc123", "description": "Event occurrence ID (required for event_occurrence_area)" }, "eventLayoutAreaId": { "type": "string", "example": "ela_abc123", "description": "Event layout area ID (required for event_occurrence_area)" }, "productId": { "type": "string", "example": "prd_abc123", "description": "Product ID (required for product)" }, "totalCapacity": { "type": "integer", "exclusiveMinimum": 0, "example": 100, "description": "Total capacity for this inventory" }, "isAllocated": { "type": "boolean", "default": false, "example": false, "description": "Whether this inventory has allocated seating" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Additional metadata" }, "accountId": { "type": "string", "example": "acc_def456", "description": "Account ID for the inventory" } }, "required": [ "sourceType", "totalCapacity", "accountId" ] } } } }, "responses": { "201": { "description": "Inventory created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List inventory", "operationId": "listInventory", "description": "List all inventory buckets for the organisation with optional filtering", "tags": [ "Inventory" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "event_occurrence_area", "product" ], "example": "event_occurrence_area", "description": "Type of inventory source" }, "required": false, "description": "Type of inventory source", "name": "sourceType", "in": "query" }, { "schema": { "type": "string", "example": "evo_abc123" }, "required": false, "name": "eventOccurrenceId", "in": "query" }, { "schema": { "type": "string", "example": "evt_abc123" }, "required": false, "name": "eventId", "in": "query" }, { "schema": { "type": "string", "example": "prd_abc123" }, "required": false, "name": "productId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "false" }, "required": false, "name": "isAllocated", "in": "query" } ], "responses": { "200": { "description": "Inventory retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/{id}": { "get": { "summary": "Get inventory", "operationId": "getInventory", "description": "Get a specific inventory bucket by ID", "tags": [ "Inventory" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Inventory retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete inventory", "operationId": "deleteInventory", "description": "Delete an inventory bucket (only if no confirmed reservations)", "tags": [ "Inventory" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Inventory deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/{id}/capacity": { "patch": { "summary": "Update inventory capacity", "operationId": "updateInventoryCapacity", "description": "Update the total capacity of an inventory bucket", "tags": [ "Inventory" ], "x-sdk-method": "updateCapacity", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCapacity": { "type": "integer", "exclusiveMinimum": 0, "example": 150, "description": "New total capacity" }, "accountId": { "type": "string", "example": "acc_def456", "description": "Account ID" } }, "required": [ "totalCapacity", "accountId" ] } } } }, "responses": { "200": { "description": "Inventory capacity updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/{id}/audit-log": { "get": { "summary": "Get inventory audit log", "operationId": "getInventoryAuditLog", "description": "Get the audit log for an inventory bucket", "tags": [ "Inventory" ], "x-sdk-method": "getAuditLog", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Audit log retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuditLogResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/{id}/seats": { "post": { "summary": "Bulk import seats", "operationId": "bulkImportSeats", "description": "Import seats into an allocated inventory bucket", "tags": [ "Inventory Seats" ], "x-sdk-method": "importSeats", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "array", "items": { "type": "object", "properties": { "eventLayoutSeatId": { "type": "string", "example": "eas_abc123", "description": "Reference to original event layout seat" }, "rowName": { "type": "string", "maxLength": 10, "example": "A", "description": "Row name" }, "seatNumber": { "type": "string", "maxLength": 10, "example": "12", "description": "Seat number" }, "priceCategory": { "type": "string", "maxLength": 50, "example": "Premium", "description": "Price category" }, "isAccessible": { "type": "boolean", "default": false, "example": false, "description": "Is accessible seat" }, "isCompanion": { "type": "boolean", "default": false, "example": false, "description": "Is companion seat" }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Additional seat attributes" } }, "required": [ "rowName", "seatNumber" ] }, "minItems": 1, "description": "List of seats to import" } }, "required": [ "seats" ] } } } }, "responses": { "201": { "description": "Seats imported successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportSeatsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List inventory seats", "operationId": "listInventorySeats", "description": "List all seats for an allocated inventory bucket", "tags": [ "Inventory Seats" ], "x-sdk-method": "listSeats", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123", "description": "Inventory ID" }, "required": true, "description": "Inventory ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "available", "reserved", "confirmed", "held", "maintenance" ], "example": "available", "description": "Seat status" }, "required": false, "description": "Seat status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "Premium" }, "required": false, "name": "priceCategory", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "false" }, "required": false, "name": "isAccessible", "in": "query" }, { "schema": { "type": "string", "example": "A" }, "required": false, "name": "rowName", "in": "query" } ], "responses": { "200": { "description": "Seats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSeatsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reserve": { "post": { "summary": "Reserve inventory", "operationId": "reserveInventory", "description": "Create a temporary reservation for GA or allocated seats", "tags": [ "Inventory Reservations" ], "x-sdk-method": "reserve", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "inventoryId": { "type": "string", "minLength": 1, "example": "inv_abc123", "description": "Inventory ID to reserve from" }, "accountId": { "type": "string", "minLength": 1, "example": "acc_xyz789", "description": "Account ID" }, "referenceType": { "type": "string", "enum": [ "order", "hold", "subscription" ], "example": "order", "description": "Type of reference (order, hold, or subscription)" }, "referenceId": { "type": "string", "minLength": 1, "example": "ord_def456", "description": "Reference ID (order, subscription, etc.)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "example": 2, "description": "Quantity for GA reservation (mutually exclusive with seatIds)" }, "seatIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "ivs_seat1", "ivs_seat2" ], "description": "Seat IDs for allocated reservation (mutually exclusive with quantity)" }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 7200, "default": 900, "example": 900, "description": "Time to live in seconds (default 900 = 15 minutes)" } }, "required": [ "inventoryId", "accountId", "referenceType", "referenceId" ] } } } }, "responses": { "201": { "description": "Inventory reserved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/check-availability": { "post": { "summary": "Check availability", "operationId": "checkAvailability", "description": "Check if requested quantity is available in inventory", "tags": [ "Inventory Reservations" ], "x-sdk-method": "checkAvailability", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "inventoryId": { "type": "string", "minLength": 1, "example": "inv_abc123", "description": "Inventory ID" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "example": 2, "description": "Quantity to check for GA" }, "seatIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "ivs_seat1", "ivs_seat2" ], "description": "Seat IDs to check for allocated" } }, "required": [ "inventoryId" ] }, "minItems": 1, "description": "List of availability check requests" } }, "required": [ "requests" ] } } } }, "responses": { "200": { "description": "Availability check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAvailabilityResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reservations": { "get": { "summary": "List reservations", "operationId": "listReservations", "description": "List all reservations with optional filtering", "tags": [ "Inventory Reservations" ], "x-sdk-method": "listReservations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "inv_abc123" }, "required": false, "name": "inventoryId", "in": "query" }, { "schema": { "type": "string", "example": "acc_xyz789" }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "enum": [ "temporary", "confirmed", "hold", "maintenance" ], "example": "temporary", "description": "Type of reservation" }, "required": false, "description": "Type of reservation", "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": [ "order", "hold", "subscription" ], "example": "order", "description": "Type of reference (order, hold, or subscription)" }, "required": false, "description": "Type of reference (order, hold, or subscription)", "name": "referenceType", "in": "query" }, { "schema": { "type": "string", "example": "ord_def456" }, "required": false, "name": "referenceId", "in": "query" } ], "responses": { "200": { "description": "Reservations retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReservationsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reservations/{id}": { "get": { "summary": "Get reservation", "operationId": "getReservation", "description": "Get a specific reservation by ID", "tags": [ "Inventory Reservations" ], "x-sdk-method": "getReservation", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ivr_abc123", "description": "Reservation ID" }, "required": true, "description": "Reservation ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "acc_def456", "description": "Account ID" }, "required": true, "description": "Account ID", "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Reservation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReservationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reservations/{id}/confirm": { "post": { "summary": "Confirm reservation", "operationId": "confirmReservation", "description": "Confirm a temporary reservation (converts reserved to confirmed)", "tags": [ "Inventory Reservations" ], "x-sdk-method": "confirmReservation", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ivr_abc123", "description": "Reservation ID" }, "required": true, "description": "Reservation ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "example": "acc_def456", "description": "Account ID" }, "referenceType": { "type": "string", "enum": [ "order", "hold", "subscription" ], "example": "order", "description": "Type of reference for this reservation" }, "referenceId": { "type": "string", "example": "ord_ghi789", "description": "Reference ID (e.g., order ID)" } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "Reservation confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmReservationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reservations/{id}/release": { "post": { "summary": "Release reservation", "operationId": "releaseReservation", "description": "Release a reservation and return inventory to available", "tags": [ "Inventory Reservations" ], "x-sdk-method": "releaseReservation", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ivr_abc123", "description": "Reservation ID" }, "required": true, "description": "Reservation ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "example": "acc_def456", "description": "Account ID" } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "Reservation released successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseReservationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/reservations/{id}/extend": { "patch": { "summary": "Extend reservation", "operationId": "extendReservation", "description": "Extend the expiry time of a temporary reservation", "tags": [ "Inventory Reservations" ], "x-sdk-method": "extendReservation", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ivr_abc123", "description": "Reservation ID" }, "required": true, "description": "Reservation ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "example": "2025-01-05T12:00:00Z", "description": "New expiration timestamp (ISO 8601)" } }, "required": [ "expiresAt" ] } } } }, "responses": { "200": { "description": "Reservation extended successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendReservationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/holds": { "post": { "summary": "Create hold", "operationId": "createHold", "description": "Create a hold on inventory (for VIPs, promoters, etc.)", "tags": [ "Inventory Holds" ], "x-sdk-method": "createHold", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "inventoryId": { "type": "string", "minLength": 1, "example": "inv_abc123", "description": "Inventory ID to hold" }, "accountId": { "type": "string", "minLength": 1, "example": "acc_xyz789", "description": "Account ID" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "example": 5, "description": "Quantity for GA hold (mutually exclusive with seatIds)" }, "seatIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "ivs_seat1", "ivs_seat2" ], "description": "Seat IDs for allocated hold (mutually exclusive with quantity)" }, "reason": { "type": "string", "minLength": 1, "maxLength": 255, "example": "VIP reservation for artist", "description": "Reason for the hold (required)" }, "heldBy": { "type": "string", "minLength": 1, "example": "usr_abc123", "description": "User ID who created the hold" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2025-01-10T18:00:00Z", "description": "Optional expiration timestamp (ISO 8601)" } }, "required": [ "inventoryId", "accountId", "reason", "heldBy" ] } } } }, "responses": { "201": { "description": "Hold created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHoldResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/inventory/holds/{id}/release": { "post": { "summary": "Release hold", "operationId": "releaseHold", "description": "Release a hold and return inventory to available", "tags": [ "Inventory Holds" ], "x-sdk-method": "releaseHold", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ivr_abc123", "description": "Hold ID" }, "required": true, "description": "Hold ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "example": "acc_def456", "description": "Account ID" } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "Hold released successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/customers": { "post": { "summary": "Create customer", "operationId": "createCustomer", "description": "Create a new customer in the organisation", "tags": [ "Customers" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID that owns this customer" }, "email": { "type": "string", "maxLength": 255, "format": "email", "example": "customer@example.com", "description": "Customer email address (must be unique per organisation)" }, "firstName": { "type": "string", "maxLength": 255, "example": "John", "description": "Customer first name" }, "lastName": { "type": "string", "maxLength": 255, "example": "Doe", "description": "Customer last name" }, "phone": { "type": "string", "maxLength": 50, "example": "+44 7700 900000", "description": "Customer phone number" }, "externalId": { "type": "string", "maxLength": 255, "example": "ext_cust_12345", "description": "External system customer ID" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "loyaltyTier": "gold", "signupSource": "web" }, "description": "Custom metadata for the customer" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List customers", "operationId": "listCustomers", "description": "List all customers with optional filtering and pagination", "tags": [ "Customers" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "john", "description": "Search customers by email, first name, or last name" }, "required": false, "description": "Search customers by email, first name, or last name", "name": "search", "in": "query" }, { "schema": { "type": "string", "example": "customer@example.com", "description": "Filter by exact email address" }, "required": false, "description": "Filter by exact email address", "name": "email", "in": "query" }, { "schema": { "type": "string", "example": "acc_xyz789", "description": "Filter by account ID" }, "required": false, "description": "Filter by account ID", "name": "accountId", "in": "query" }, { "schema": { "type": "string", "example": "false", "description": "Filter by blocked status (true/false)" }, "required": false, "description": "Filter by blocked status (true/false)", "name": "isBlocked", "in": "query" }, { "schema": { "type": "string", "example": "2024-06-01T00:00:00Z", "description": "Only customers updated at/after this ISO timestamp (for incremental polling)" }, "required": false, "description": "Only customers updated at/after this ISO timestamp (for incremental polling)", "name": "updatedSince", "in": "query" }, { "schema": { "type": "string", "description": "Opaque keyset cursor for stable pagination (use pagination.nextCursor from the previous page)" }, "required": false, "description": "Opaque keyset cursor for stable pagination (use pagination.nextCursor from the previous page)", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "default": "1", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "20", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Customers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCustomersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/customers/{customerId}": { "get": { "summary": "Get customer", "operationId": "getCustomer", "description": "Get a specific customer by ID", "tags": [ "Customers" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_abc123", "description": "Customer ID" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update customer", "operationId": "updateCustomer", "description": "Update an existing customer", "tags": [ "Customers" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_abc123", "description": "Customer ID" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 255, "format": "email", "example": "newemail@example.com", "description": "Customer email address" }, "firstName": { "type": [ "string", "null" ], "maxLength": 255, "example": "Jane", "description": "Customer first name" }, "lastName": { "type": [ "string", "null" ], "maxLength": 255, "example": "Smith", "description": "Customer last name" }, "phone": { "type": [ "string", "null" ], "maxLength": 50, "example": "+44 7700 900001", "description": "Customer phone number" }, "externalId": { "type": [ "string", "null" ], "maxLength": 255, "example": "ext_cust_67890", "description": "External system customer ID" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "example": { "loyaltyTier": "platinum" }, "description": "Custom metadata for the customer" } } } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/customers/{customerId}/block": { "post": { "summary": "Block customer", "operationId": "blockCustomer", "description": "Block a customer from making purchases", "tags": [ "Customers" ], "x-sdk-method": "block", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_abc123", "description": "Customer ID" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "example": "Repeated chargebacks", "description": "Reason for blocking the customer" } } } } } }, "responses": { "200": { "description": "Customer blocked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/customers/{customerId}/unblock": { "post": { "summary": "Unblock customer", "operationId": "unblockCustomer", "description": "Unblock a previously blocked customer", "tags": [ "Customers" ], "x-sdk-method": "unblock", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_abc123", "description": "Customer ID" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Customer unblocked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders": { "post": { "summary": "Create order", "operationId": "createOrder", "description": "Create a new order with optional line items", "tags": [ "Orders" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID that owns this order" }, "customerId": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_abc123", "description": "Customer ID (optional for guest checkout)" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "GBP", "example": "GBP", "description": "Currency code (ISO 4217)" }, "channel": { "type": "string", "maxLength": 50, "example": "web", "description": "Sales channel (web, mobile, pos, api)" }, "isGuestCheckout": { "type": "boolean", "default": false, "example": false, "description": "Whether this is a guest checkout" }, "customerNotes": { "type": "string", "maxLength": 2000, "example": "Please contact me before delivery", "description": "Notes from the customer" }, "internalNotes": { "type": "string", "maxLength": 2000, "example": "VIP customer - priority handling", "description": "Internal notes (not visible to customer)" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "promoCode": "SUMMER20" }, "description": "Custom metadata" }, "expiresInMinutes": { "type": "integer", "exclusiveMinimum": 0, "example": 15, "description": "Order expiry time in minutes (defaults to 15)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ticket", "product", "addon", "fee", "tax", "discount" ], "example": "ticket", "description": "Type of line item" }, "name": { "type": "string", "maxLength": 255, "example": "General Admission", "description": "Line item name" }, "description": { "type": "string", "maxLength": 1000, "example": "Entry to main event area", "description": "Line item description" }, "unitPrice": { "type": "integer", "minimum": 0, "example": 2500, "description": "Unit price in integer minor units (e.g. 2500 = £25.00)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "default": 1, "example": 2, "description": "Quantity (defaults to 1)" }, "ticketDetails": { "type": "object", "additionalProperties": {}, "example": { "eventId": "evt_123", "ticketTypeId": "tt_456" }, "description": "Ticket-specific details" }, "productDetails": { "type": "object", "additionalProperties": {}, "example": { "productId": "prod_123", "sku": "TSHIRT-L" }, "description": "Product-specific details" }, "feeDetails": { "type": "object", "additionalProperties": {}, "example": { "feeType": "service_fee" }, "description": "Fee-specific details" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "source": "web" }, "description": "Custom metadata" } }, "required": [ "type", "name", "unitPrice" ] }, "description": "Initial line items to add to the order" } }, "required": [ "accountId" ] } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List orders", "operationId": "listOrders", "description": "List all orders with optional filtering and pagination", "tags": [ "Orders" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "confirmed", "processing", "completed", "cancelled", "refunded", "expired", "failed" ], "example": "pending", "description": "Filter by order status" }, "required": false, "description": "Filter by order status", "name": "status", "in": "query" }, { "schema": { "type": "string", "example": "cus_abc123", "description": "Filter by customer ID" }, "required": false, "description": "Filter by customer ID", "name": "customerId", "in": "query" }, { "schema": { "type": "string", "example": "web", "description": "Filter by sales channel" }, "required": false, "description": "Filter by sales channel", "name": "channel", "in": "query" }, { "schema": { "type": "string", "example": "2024-01-01T00:00:00Z", "description": "Filter by created date (from)" }, "required": false, "description": "Filter by created date (from)", "name": "fromDate", "in": "query" }, { "schema": { "type": "string", "example": "2024-12-31T23:59:59Z", "description": "Filter by created date (to)" }, "required": false, "description": "Filter by created date (to)", "name": "toDate", "in": "query" }, { "schema": { "type": "string", "example": "2024-06-01T00:00:00Z", "description": "Only orders updated at/after this ISO timestamp (for incremental polling)" }, "required": false, "description": "Only orders updated at/after this ISO timestamp (for incremental polling)", "name": "updatedSince", "in": "query" }, { "schema": { "type": "string", "example": "MjAyNi0wNi0xM...", "description": "Opaque keyset cursor for stable pagination (use the pagination.nextCursor from the previous page)" }, "required": false, "description": "Opaque keyset cursor for stable pagination (use the pagination.nextCursor from the previous page)", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "example": "ORD-ABC123", "description": "Search by order number" }, "required": false, "description": "Search by order number", "name": "search", "in": "query" }, { "schema": { "type": "string", "default": "1", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "20", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrdersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}": { "get": { "summary": "Get order", "operationId": "getOrder", "description": "Get a specific order by ID", "tags": [ "Orders" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update order", "operationId": "updateOrder", "description": "Update an existing order", "tags": [ "Orders" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "pattern": "^cus_[a-zA-Z0-9]+$", "example": "cus_newcust123", "description": "New customer ID" }, "customerNotes": { "type": "string", "maxLength": 2000, "example": "Updated delivery instructions", "description": "Updated customer notes" }, "internalNotes": { "type": "string", "maxLength": 2000, "example": "Escalated to manager", "description": "Updated internal notes" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "priority": "high" }, "description": "Updated metadata (merged with existing)" }, "extendExpiry": { "type": "boolean", "example": true, "description": "Extend the order expiry time" }, "addItems": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ticket", "product", "addon", "fee", "tax", "discount" ], "example": "ticket", "description": "Type of line item" }, "name": { "type": "string", "maxLength": 255, "example": "General Admission", "description": "Line item name" }, "description": { "type": "string", "maxLength": 1000, "example": "Entry to main event area", "description": "Line item description" }, "unitPrice": { "type": "integer", "minimum": 0, "example": 2500, "description": "Unit price in integer minor units (e.g. 2500 = £25.00)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "default": 1, "example": 2, "description": "Quantity (defaults to 1)" }, "ticketDetails": { "type": "object", "additionalProperties": {}, "example": { "eventId": "evt_123", "ticketTypeId": "tt_456" }, "description": "Ticket-specific details" }, "productDetails": { "type": "object", "additionalProperties": {}, "example": { "productId": "prod_123", "sku": "TSHIRT-L" }, "description": "Product-specific details" }, "feeDetails": { "type": "object", "additionalProperties": {}, "example": { "feeType": "service_fee" }, "description": "Fee-specific details" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "source": "web" }, "description": "Custom metadata" } }, "required": [ "type", "name", "unitPrice" ] }, "description": "Line items to add to the order" }, "updateItems": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "pattern": "^oli_[a-zA-Z0-9]+$", "example": "oli_abc123", "description": "Line item ID" }, "updates": { "type": "object", "properties": { "quantity": { "type": "integer", "exclusiveMinimum": 0, "example": 3, "description": "New quantity" }, "unitPrice": { "type": "integer", "minimum": 0, "example": 3000, "description": "New unit price in integer minor units (e.g. 3000 = £30.00)" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "updated": true }, "description": "Updated metadata" } } } }, "required": [ "itemId", "updates" ] }, "description": "Line items to update" }, "removeItems": { "type": "array", "items": { "type": "string", "pattern": "^oli_[a-zA-Z0-9]+$" }, "example": [ "oli_remove1", "oli_remove2" ], "description": "Line item IDs to remove" } } } } } }, "responses": { "200": { "description": "Order updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/number/{orderNumber}": { "get": { "summary": "Get order by number", "operationId": "getOrderByNumber", "description": "Get a specific order by order number", "tags": [ "Orders" ], "x-sdk-method": "getByNumber", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ORD-ABC123", "description": "Order number" }, "required": true, "description": "Order number", "name": "orderNumber", "in": "path" } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/cancel": { "post": { "summary": "Cancel order", "operationId": "cancelOrder", "description": "Cancel an order with a reason", "tags": [ "Orders" ], "x-sdk-method": "cancel", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "example": "Customer requested cancellation", "description": "Reason for cancellation" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Order cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/status": { "post": { "summary": "Transition order status", "operationId": "transitionOrderStatus", "description": "Transition an order to a new status", "tags": [ "Orders" ], "x-sdk-method": "transitionStatus", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "confirmed", "processing", "completed", "cancelled", "refunded", "expired", "failed" ], "example": "confirmed", "description": "New order status" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Order status transitioned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionOrderStatusResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/validate": { "post": { "summary": "Validate order", "operationId": "validateOrder", "description": "Validate an order before payment (check inventory, pricing, etc.)", "tags": [ "Orders" ], "x-sdk-method": "validate", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Validate order request (no body required)" } } } }, "responses": { "200": { "description": "Order validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/items": { "post": { "summary": "Add line item", "operationId": "addOrderLineItem", "description": "Add a line item to an order", "tags": [ "Orders" ], "x-sdk-method": "addItem", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ticket", "product", "addon", "fee", "tax", "discount" ], "example": "ticket", "description": "Type of line item" }, "name": { "type": "string", "maxLength": 255, "example": "General Admission", "description": "Line item name" }, "description": { "type": "string", "maxLength": 1000, "example": "Entry to main event area", "description": "Line item description" }, "unitPrice": { "type": "integer", "minimum": 0, "example": 2500, "description": "Unit price in integer minor units (e.g. 2500 = £25.00)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "default": 1, "example": 2, "description": "Quantity (defaults to 1)" }, "ticketDetails": { "type": "object", "additionalProperties": {}, "example": { "eventId": "evt_123", "ticketTypeId": "tt_456" }, "description": "Ticket-specific details" }, "productDetails": { "type": "object", "additionalProperties": {}, "example": { "productId": "prod_123", "sku": "TSHIRT-L" }, "description": "Product-specific details" }, "feeDetails": { "type": "object", "additionalProperties": {}, "example": { "feeType": "service_fee" }, "description": "Fee-specific details" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "source": "web" }, "description": "Custom metadata" } }, "required": [ "type", "name", "unitPrice" ] } } } }, "responses": { "201": { "description": "Line item added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLineItemResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/items/{itemId}": { "patch": { "summary": "Update line item", "operationId": "updateOrderLineItem", "description": "Update a line item in an order", "tags": [ "Orders" ], "x-sdk-method": "updateItem", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" }, { "schema": { "type": "string", "pattern": "^oli_[a-zA-Z0-9]+$", "example": "oli_abc123", "description": "Line item ID" }, "required": true, "description": "Line item ID", "name": "itemId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "exclusiveMinimum": 0, "example": 3, "description": "New quantity" }, "unitPrice": { "type": "integer", "minimum": 0, "example": 3000, "description": "New unit price in integer minor units (e.g. 3000 = £30.00)" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "updated": true }, "description": "Updated metadata" } } } } } }, "responses": { "200": { "description": "Line item updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLineItemResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Remove line item", "operationId": "removeOrderLineItem", "description": "Remove a line item from an order", "tags": [ "Orders" ], "x-sdk-method": "removeItem", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" }, { "schema": { "type": "string", "pattern": "^oli_[a-zA-Z0-9]+$", "example": "oli_abc123", "description": "Line item ID" }, "required": true, "description": "Line item ID", "name": "itemId", "in": "path" } ], "responses": { "200": { "description": "Line item removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveLineItemResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/payment": { "post": { "summary": "Initiate payment", "operationId": "initiateOrderPayment", "description": "Initiate payment for an order", "tags": [ "Orders" ], "x-sdk-method": "initiatePayment", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ], "example": "online_card", "description": "The type of payment method to use" }, "returnUrl": { "type": "string", "format": "uri", "example": "https://example.com/checkout/complete", "description": "URL to redirect to after payment (for 3DS, etc.)" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "source": "web_checkout", "promoCode": "SUMMER20" }, "description": "Additional metadata to attach to the payment" } }, "required": [ "paymentMethod" ] } } } }, "responses": { "200": { "description": "Payment initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiatePaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/payment/status": { "get": { "summary": "Get payment status", "operationId": "getOrderPaymentStatus", "description": "Get the current payment status for an order", "tags": [ "Orders" ], "x-sdk-method": "getPaymentStatus", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentStatusResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/passes/{passId}/ticket.pdf": { "get": { "summary": "Download a pass as a PDF ticket", "operationId": "getOrderPassPdf", "description": "Render and stream a single pass as a PDF ticket (application/pdf). Staff surface; browsers fetch this directly rather than through the typed SDK.", "tags": [ "Orders" ], "x-sdk-method": "getPassPdf", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ord_abc123xyz789" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "required": true, "name": "passId", "in": "path" } ], "responses": { "200": { "description": "PDF ticket (application/pdf)" }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/resend-confirmation": { "post": { "summary": "Resend order confirmation email", "operationId": "resendOrderConfirmation", "description": "Resend the buyer's confirmation email for a confirmed order, with the ticket PDFs attached and a link to the hosted confirmation page. Bypasses the once-per-order send marker. Staff surface.", "tags": [ "Orders" ], "x-sdk-method": "resendConfirmation", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Confirmation email sent (or skipped, with a reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendOrderConfirmationResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/passes": { "get": { "summary": "Get order passes", "operationId": "getOrderPasses", "description": "List the passes, entitlements and redemptions issued for an order (the order's tickets). Staff surface - includes the redemption barcode.", "tags": [ "Orders" ], "x-sdk-method": "getPasses", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123xyz789", "description": "Order ID" }, "required": true, "description": "Order ID", "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Order passes/entitlements/redemptions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderPassesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payments": { "post": { "summary": "Create payment", "operationId": "createPayment", "description": "Create a new payment for an order", "tags": [ "Payments" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID for tenant isolation" }, "orderId": { "type": "string", "pattern": "^ord_[a-zA-Z0-9]+$", "example": "ord_abc123", "description": "Order ID this payment is for" }, "orderNumber": { "type": "string", "maxLength": 50, "example": "ORD-ABC123", "description": "Human-readable order number" }, "amount": { "type": "number", "exclusiveMinimum": 0, "example": 97, "description": "Payment amount" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "GBP", "description": "Currency code (ISO 4217)" }, "paymentType": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ], "example": "online_card", "description": "Type of payment" }, "paymentProviderId": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123", "description": "Payment provider ID (optional - will find by type if not provided)" }, "returnUrl": { "type": "string", "format": "uri", "example": "https://venue.com/orders/ord_xxx/confirmation", "description": "URL to redirect after payment" }, "isPartialPayment": { "type": "boolean", "default": false, "example": false, "description": "Whether this is a partial payment" }, "remainingBalance": { "type": "number", "minimum": 0, "example": 0, "description": "Remaining balance after this payment" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "customerEmail": "customer@example.com" }, "description": "Custom metadata" } }, "required": [ "accountId", "orderId", "orderNumber", "amount", "currency", "paymentType" ] } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List payments", "operationId": "listPayments", "description": "List all payments with optional filtering and pagination", "tags": [ "Payments" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ord_abc123", "description": "Filter by order ID" }, "required": false, "description": "Filter by order ID", "name": "orderId", "in": "query" }, { "schema": { "type": "string", "enum": [ "created", "pending", "requires_action", "processing", "succeeded", "failed", "cancelled", "expired" ], "example": "succeeded", "description": "Filter by payment status" }, "required": false, "description": "Filter by payment status", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ], "example": "online_card", "description": "Filter by payment type" }, "required": false, "description": "Filter by payment type", "name": "paymentType", "in": "query" }, { "schema": { "type": "string", "example": "pp_stripeXxx123", "description": "Filter by payment provider" }, "required": false, "description": "Filter by payment provider", "name": "paymentProviderId", "in": "query" }, { "schema": { "type": "string", "example": "2024-01-01T00:00:00Z", "description": "Filter by created date (from)" }, "required": false, "description": "Filter by created date (from)", "name": "fromDate", "in": "query" }, { "schema": { "type": "string", "example": "2024-12-31T23:59:59Z", "description": "Filter by created date (to)" }, "required": false, "description": "Filter by created date (to)", "name": "toDate", "in": "query" }, { "schema": { "type": "string", "default": "1", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "20", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaymentsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payments/{paymentId}": { "get": { "summary": "Get payment", "operationId": "getPayment", "description": "Get a specific payment by ID", "tags": [ "Payments" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^pay_[a-zA-Z0-9]+$", "example": "pay_abc123xyz789", "description": "Payment ID" }, "required": true, "description": "Payment ID", "name": "paymentId", "in": "path" } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payments/{paymentId}/cancel": { "post": { "summary": "Cancel payment", "operationId": "cancelPayment", "description": "Cancel a pending payment", "tags": [ "Payments" ], "x-sdk-method": "cancel", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^pay_[a-zA-Z0-9]+$", "example": "pay_abc123xyz789", "description": "Payment ID" }, "required": true, "description": "Payment ID", "name": "paymentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "example": "Customer requested cancellation", "description": "Reason for cancellation" } } } } } }, "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payments/{paymentId}/refunds": { "post": { "summary": "Create refund", "operationId": "createPaymentRefund", "description": "Create a refund for a payment", "tags": [ "Payments" ], "x-sdk-method": "createRefund", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^pay_[a-zA-Z0-9]+$", "example": "pay_abc123xyz789", "description": "Payment ID" }, "required": true, "description": "Payment ID", "name": "paymentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "example": 48.5, "description": "Refund amount" }, "reason": { "type": "string", "minLength": 1, "maxLength": 100, "example": "requested_by_customer", "description": "Reason for refund" }, "notes": { "type": "string", "maxLength": 1000, "example": "Customer unable to attend", "description": "Additional notes" }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "ticketNumber": "T-001" }, "description": "Custom metadata" } }, "required": [ "amount", "reason" ] } } } }, "responses": { "201": { "description": "Refund created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List refunds", "operationId": "listPaymentRefunds", "description": "List all refunds for a specific payment", "tags": [ "Payments" ], "x-sdk-method": "listRefunds", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^pay_[a-zA-Z0-9]+$", "example": "pay_abc123xyz789", "description": "Payment ID" }, "required": true, "description": "Payment ID", "name": "paymentId", "in": "path" } ], "responses": { "200": { "description": "Refunds retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRefundsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers": { "post": { "summary": "Create payment provider", "operationId": "createPaymentProvider", "description": "Create a new payment provider configuration", "tags": [ "Payment Providers" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$", "example": "acc_xyz789", "description": "Account ID (optional - null for org-wide provider)" }, "type": { "type": "string", "enum": [ "stripe_connect", "stripe_direct", "adyen", "square", "paypal", "cash", "bank_transfer" ], "example": "stripe_connect", "description": "Payment provider type" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Main Stripe Account", "description": "Provider display name" }, "description": { "type": "string", "maxLength": 1000, "example": "Primary payment processor for online orders", "description": "Provider description" }, "integrationType": { "type": "string", "enum": [ "ticketlayer_pay", "self_service" ], "default": "self_service", "example": "ticketlayer_pay", "description": "Integration type: ticketlayer_pay (managed by Ticketlayer, one per org) or self_service (default)" }, "integrationServiceUrl": { "type": "string", "format": "uri", "example": "https://stripe.paymentintegration.ticketlayer.com", "description": "Integration service URL (optional - uses default for type)" }, "integrationServiceVersion": { "type": "string", "maxLength": 10, "default": "v1", "example": "v1", "description": "Integration service API version" }, "configuration": { "type": "object", "additionalProperties": {}, "example": { "stripeConnectedAccountId": "acct_xxx" }, "description": "Provider-specific configuration" }, "supportedPaymentTypes": { "type": "array", "items": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ] }, "minItems": 1, "example": [ "online_card", "online_wallet" ], "description": "Supported payment types" }, "capabilities": { "type": "object", "properties": { "supportsInstantCapture": { "type": "boolean", "example": true, "description": "Supports instant capture" }, "supportsDelayedCapture": { "type": "boolean", "example": true, "description": "Supports delayed capture" }, "supportsRefunds": { "type": "boolean", "example": true, "description": "Supports refunds" }, "supportsPartialRefunds": { "type": "boolean", "example": true, "description": "Supports partial refunds" }, "requiresCustomerAction": { "type": "boolean", "example": true, "description": "Requires customer action (3DS, etc.)" }, "supportedCurrencies": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 3 }, "example": [ "GBP", "USD", "EUR" ], "description": "Supported currencies" }, "maxAmount": { "type": "number", "exclusiveMinimum": 0, "example": 10000, "description": "Maximum transaction amount" }, "minAmount": { "type": "number", "minimum": 0, "example": 0.5, "description": "Minimum transaction amount" } }, "description": "Provider capabilities (optional - uses defaults for type)" }, "isDefault": { "type": "boolean", "default": false, "example": true, "description": "Set as default provider for this account/org" }, "priority": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100, "description": "Provider priority (lower = higher priority)" }, "feeStructure": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "percentage_plus_fixed" ], "example": "percentage_plus_fixed", "description": "Fee structure type" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "example": 2.9, "description": "Percentage fee" }, "fixed": { "type": "number", "minimum": 0, "example": 0.2, "description": "Fixed fee amount" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "GBP", "description": "Currency for fixed fee" } }, "required": [ "type" ], "description": "Fee structure for this provider" }, "applicationFee": { "allOf": [ { "$ref": "#/components/schemas/ApplicationFee" }, { "description": "Application fee configuration (for platform)" } ] }, "metadata": { "type": "object", "additionalProperties": {}, "example": { "environment": "production" }, "description": "Custom metadata" } }, "required": [ "type", "name", "configuration", "supportedPaymentTypes" ] } } } }, "responses": { "201": { "description": "Payment provider created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List payment providers", "operationId": "listPaymentProviders", "description": "List all payment providers with optional filtering and pagination", "tags": [ "Payment Providers" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "acc_xyz789", "description": "Filter by account ID" }, "required": false, "description": "Filter by account ID", "name": "accountId", "in": "query" }, { "schema": { "type": "string", "enum": [ "stripe_connect", "stripe_direct", "adyen", "square", "paypal", "cash", "bank_transfer" ], "example": "stripe_connect", "description": "Filter by provider type" }, "required": false, "description": "Filter by provider type", "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "inactive", "pending_setup" ], "example": "active", "description": "Filter by status" }, "required": false, "description": "Filter by status", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ], "example": "online_card", "description": "Filter by supported payment type" }, "required": false, "description": "Filter by supported payment type", "name": "paymentType", "in": "query" }, { "schema": { "type": "string", "example": "true", "description": "Filter for default providers" }, "required": false, "description": "Filter for default providers", "name": "isDefault", "in": "query" }, { "schema": { "type": "string", "enum": [ "ticketlayer_pay", "self_service" ], "example": "ticketlayer_pay", "description": "Filter by integration type" }, "required": false, "description": "Filter by integration type", "name": "integrationType", "in": "query" }, { "schema": { "type": "string", "default": "1", "example": "1", "description": "Page number" }, "required": false, "description": "Page number", "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "20", "example": "20", "description": "Items per page (max 100)" }, "required": false, "description": "Items per page (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Payment providers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaymentProvidersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/default": { "get": { "summary": "Get default payment provider", "operationId": "getDefaultPaymentProvider", "description": "Get the default payment provider for the account/organisation", "tags": [ "Payment Providers" ], "x-sdk-method": "getDefault", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Default payment provider retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/{providerId}": { "get": { "summary": "Get payment provider", "operationId": "getPaymentProvider", "description": "Get a specific payment provider by ID", "tags": [ "Payment Providers" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123", "description": "Payment Provider ID" }, "required": true, "description": "Payment Provider ID", "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Payment provider retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update payment provider", "operationId": "updatePaymentProvider", "description": "Update an existing payment provider configuration", "tags": [ "Payment Providers" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123", "description": "Payment Provider ID" }, "required": true, "description": "Payment Provider ID", "name": "providerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Updated Provider Name", "description": "Provider display name" }, "description": { "type": "string", "maxLength": 1000, "example": "Updated description", "description": "Provider description" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending_setup" ], "example": "active", "description": "Provider status" }, "integrationServiceUrl": { "type": "string", "format": "uri", "example": "https://stripe.paymentintegration.ticketlayer.com", "description": "Integration service URL" }, "integrationServiceVersion": { "type": "string", "maxLength": 10, "example": "v2", "description": "Integration service API version" }, "configuration": { "type": "object", "additionalProperties": {}, "example": { "webhookSecret": "whsec_xxx" }, "description": "Provider-specific configuration (merged with existing)" }, "supportedPaymentTypes": { "type": "array", "items": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet", "in_person_card", "in_person_cash", "bank_transfer", "cheque" ] }, "minItems": 1, "example": [ "online_card", "online_wallet", "in_person_card" ], "description": "Supported payment types" }, "capabilities": { "type": "object", "properties": { "supportsInstantCapture": { "type": "boolean", "example": true, "description": "Supports instant capture" }, "supportsDelayedCapture": { "type": "boolean", "example": true, "description": "Supports delayed capture" }, "supportsRefunds": { "type": "boolean", "example": true, "description": "Supports refunds" }, "supportsPartialRefunds": { "type": "boolean", "example": true, "description": "Supports partial refunds" }, "requiresCustomerAction": { "type": "boolean", "example": true, "description": "Requires customer action (3DS, etc.)" }, "supportedCurrencies": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 3 }, "example": [ "GBP", "USD", "EUR" ], "description": "Supported currencies" }, "maxAmount": { "type": "number", "exclusiveMinimum": 0, "example": 10000, "description": "Maximum transaction amount" }, "minAmount": { "type": "number", "minimum": 0, "example": 0.5, "description": "Minimum transaction amount" } }, "description": "Provider capabilities (merged with existing)" }, "isDefault": { "type": "boolean", "example": true, "description": "Set as default provider" }, "priority": { "type": "integer", "minimum": 1, "maximum": 1000, "example": 50, "description": "Provider priority" }, "feeStructure": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "percentage_plus_fixed" ], "example": "percentage_plus_fixed", "description": "Fee structure type" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "example": 2.9, "description": "Percentage fee" }, "fixed": { "type": "number", "minimum": 0, "example": 0.2, "description": "Fixed fee amount" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "GBP", "description": "Currency for fixed fee" } }, "required": [ "type" ], "description": "Fee structure" }, "applicationFee": { "$ref": "#/components/schemas/ApplicationFee" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Custom metadata (merged with existing)" } } } } } }, "responses": { "200": { "description": "Payment provider updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete payment provider", "operationId": "deletePaymentProvider", "description": "Delete a payment provider (soft delete)", "tags": [ "Payment Providers" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123", "description": "Payment Provider ID" }, "required": true, "description": "Payment Provider ID", "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Payment provider deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePaymentProviderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/ticketlayer-pay/enable": { "post": { "summary": "Enable Ticketlayer Pay", "operationId": "enableTicketlayerPay", "description": "Vend the organisation's connected account on Ticketlayer's Stripe platform and create its Ticketlayer Pay provider. Idempotent: a second call returns the existing provider.", "tags": [ "Payment Providers" ], "x-sdk-method": "enableTicketlayerPay", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Riverside Rowing Club", "description": "Name Stripe shows the merchant; defaults to the organisation name" }, "contactEmail": { "type": "string", "format": "email", "example": "treasurer@example.org" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "GB", "description": "ISO 3166-1 alpha-2, default GB" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "gbp", "description": "ISO 4217, default gbp" }, "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "Already enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableTicketlayerPayResponse" } } } }, "201": { "description": "Enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableTicketlayerPayResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/ticketlayer-pay": { "get": { "summary": "Ticketlayer Pay status", "operationId": "getTicketlayerPay", "description": "Onboarding and charge state of the organisation's Ticketlayer Pay account; refresh=true re-reads Stripe first.", "tags": [ "Payment Providers" ], "x-sdk-method": "getTicketlayerPay", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ], "example": "true", "description": "Re-read the account from Stripe before answering" }, "required": false, "description": "Re-read the account from Stripe before answering", "name": "refresh", "in": "query" } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/TicketlayerPayStatus" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/ticketlayer-pay/onboarding-session": { "post": { "summary": "Account Session for embedded Ticketlayer Pay onboarding", "operationId": "createTicketlayerPayOnboardingSession", "description": "Mints a Stripe Account Session for the embedded account-onboarding, account-management and notification-banner components.", "tags": [ "Payment Providers" ], "x-sdk-method": "createTicketlayerPayOnboardingSession", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "201": { "description": "Session minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectOnboardingSession" } }, "required": [ "session" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/ticketlayer-pay/onboarding-link": { "post": { "summary": "Hosted onboarding link for Ticketlayer Pay", "operationId": "createTicketlayerPayOnboardingLink", "tags": [ "Payment Providers" ], "x-sdk-method": "createTicketlayerPayOnboardingLink", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://wis.example.com/api/onboarding/stripe/return?session=abc", "description": "Where Stripe sends the user after the hosted flow" }, "refreshUrl": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://wis.example.com/api/onboarding/stripe/refresh?session=abc", "description": "Where Stripe sends the user when the link has expired" } }, "required": [ "returnUrl", "refreshUrl" ] } } } }, "responses": { "201": { "description": "Link minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectOnboardingLinkResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/stripe-connect": { "post": { "summary": "Link the organisation's own Stripe account", "operationId": "linkStripeConnect", "description": "Validates the keys against Stripe, stores them encrypted, registers the webhook endpoints and creates (or re-keys) the organisation's stripe_connect provider.", "tags": [ "Payment Providers" ], "x-sdk-method": "linkStripeConnect", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "secretKey": { "type": "string", "pattern": "^(sk|rk)_(test|live)_[A-Za-z0-9]+$", "example": "sk_test_51...", "description": "The organisation's Stripe secret key (stored encrypted, never returned)" }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_[A-Za-z0-9]+$", "example": "pk_test_51..." }, "defaultMode": { "type": "string", "enum": [ "direct", "connected" ], "example": "direct", "description": "How Accounts with no routing row of their own charge: direct on this Stripe account, or through a connected account each" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Stripe" }, "applicationFee": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "percentage_plus_fixed" ], "example": "percentage_plus_fixed" }, "value": { "type": "number", "minimum": 0, "example": 1, "description": "Legacy single value: percent for percentage, minor units for fixed" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "example": 1, "description": "Percent of the charge" }, "fixed": { "type": "integer", "minimum": 0, "example": 10, "description": "Minor units per charge" } }, "required": [ "type" ], "description": "The organisation's own fee on charges through its connected accounts" }, "refundApplicationFee": { "type": "boolean", "example": true, "description": "Return the application fee (proportionally) when a charge is refunded" } }, "required": [ "secretKey", "publishableKey", "defaultMode" ] } } } }, "responses": { "200": { "description": "Existing provider re-keyed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkStripeConnectResponse" } } } }, "201": { "description": "Provider created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkStripeConnectResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "The organisation's Stripe Connect provider", "operationId": "getStripeConnect", "tags": [ "Payment Providers" ], "x-sdk-method": "getStripeConnect", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Provider, or null when none is linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "allOf": [ { "$ref": "#/components/schemas/StripeConnectProvider" }, { "type": [ "object", "null" ] } ] } }, "required": [ "provider" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/{providerId}/accounts": { "get": { "summary": "Per-Account routing rows on a Stripe Connect provider", "operationId": "listPaymentProviderAccounts", "tags": [ "Payment Providers" ], "x-sdk-method": "listAccounts", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123", "description": "Payment Provider ID" }, "required": true, "description": "Payment Provider ID", "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentProviderAccount" } } }, "required": [ "accounts" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/{providerId}/accounts/{accountId}": { "get": { "summary": "One Account's routing on a Stripe Connect provider", "operationId": "getPaymentProviderAccount", "tags": [ "Payment Providers" ], "x-sdk-method": "getAccount", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123" }, "required": true, "name": "providerId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "acc_abc123" }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ], "example": "true", "description": "Re-read the account from Stripe before answering" }, "required": false, "description": "Re-read the account from Stripe before answering", "name": "refresh", "in": "query" } ], "responses": { "200": { "description": "Row, or null when the provider default applies", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "allOf": [ { "$ref": "#/components/schemas/PaymentProviderAccount" }, { "type": [ "object", "null" ] } ] } }, "required": [ "account" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "put": { "summary": "Set how an Account charges through a Stripe Connect provider", "operationId": "setPaymentProviderAccountMode", "description": "direct charges the organisation's own Stripe account; connected links the given connected account, reuses the one already on the row, or vends a new Stripe v2 account (Stripe liable, no dashboard) for this Account.", "tags": [ "Payment Providers" ], "x-sdk-method": "setAccountMode", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123" }, "required": true, "name": "providerId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "acc_abc123" }, "required": true, "name": "accountId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "direct", "connected" ], "example": "connected" }, "connectedAccountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9]+$", "example": "acct_1AbCdEfGhIjKlMnO", "description": "An existing connected account on the organisation's Stripe platform to link; omit to vend one" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Riverside Rowing Club" }, "contactEmail": { "type": "string", "format": "email" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "GB" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "gbp" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Row", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/PaymentProviderAccount" } }, "required": [ "account" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/{providerId}/accounts/{accountId}/onboarding-session": { "post": { "summary": "Account Session for embedded onboarding of an Account's connected account", "operationId": "createPaymentProviderAccountOnboardingSession", "tags": [ "Payment Providers" ], "x-sdk-method": "createAccountOnboardingSession", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123" }, "required": true, "name": "providerId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "acc_abc123" }, "required": true, "name": "accountId", "in": "path" } ], "responses": { "201": { "description": "Session minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectOnboardingSession" } }, "required": [ "session" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/payment-providers/{providerId}/accounts/{accountId}/onboarding-link": { "post": { "summary": "Hosted onboarding link for an Account's connected account", "operationId": "createPaymentProviderAccountOnboardingLink", "tags": [ "Payment Providers" ], "x-sdk-method": "createAccountOnboardingLink", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ppr_[a-zA-Z0-9]+$", "example": "ppr_stripeXxx123" }, "required": true, "name": "providerId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "acc_abc123" }, "required": true, "name": "accountId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://wis.example.com/api/onboarding/stripe/return?session=abc", "description": "Where Stripe sends the user after the hosted flow" }, "refreshUrl": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://wis.example.com/api/onboarding/stripe/refresh?session=abc", "description": "Where Stripe sends the user when the link has expired" } }, "required": [ "returnUrl", "refreshUrl" ] } } } }, "responses": { "201": { "description": "Link minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectOnboardingLinkResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels": { "post": { "summary": "Create sales channel", "operationId": "createSalesChannel", "description": "Create a sales channel: a policy bundle describing where and under what commercial rules tickets are sold", "tags": [ "Sales Channels" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 2000 }, "channelType": { "type": "string", "enum": [ "website", "embed", "box_office", "kiosk", "reseller_api", "internal" ] }, "channelTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "tagged" ] }, "channelTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "mode" ] }, "pricingConfig": { "type": "object", "properties": { "showMemberPricing": { "type": "boolean" }, "showOriginalPrice": { "type": "boolean" }, "includeFeesInPrice": { "type": "boolean" } } }, "customerConfig": { "type": "object", "properties": { "requireLogin": { "type": "boolean" }, "allowGuestCheckout": { "type": "boolean" }, "collectPhone": { "type": "boolean" }, "collectAddress": { "type": "boolean" } } }, "customerFacing": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "subdomain": { "type": "string", "minLength": 1, "maxLength": 63 }, "customDomain": { "type": "string", "minLength": 1, "maxLength": 255 }, "allowedOrigins": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^https?:\\/\\/[*a-zA-Z0-9.:-]+$" } ] } }, "magicLinkBaseUrl": { "type": "string", "format": "uri" }, "partnerIdentity": { "type": "object", "properties": { "issuer": { "type": "string", "minLength": 1 }, "publicKeyPem": { "type": "string", "minLength": 1 }, "algorithm": { "type": "string", "enum": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512" ] } }, "required": [ "issuer", "publicKeyPem", "algorithm" ] } } }, "reservationTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 3600 }, "checkoutTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 1800 }, "receivingAccountId": { "type": "string", "minLength": 1 }, "feeProfileId": { "type": "string", "minLength": 1 } }, "required": [ "accountId", "name", "slug", "channelType" ] } } } }, "responses": { "201": { "description": "Sales channel created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List sales channels", "operationId": "listSalesChannels", "description": "List the organisation's sales channels visible to the caller", "tags": [ "Sales Channels" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Sales channels retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSalesChannelsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}": { "get": { "summary": "Get sales channel", "operationId": "getSalesChannel", "description": "Get a sales channel by ID", "tags": [ "Sales Channels" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Sales channel retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update sales channel", "operationId": "updateSalesChannel", "description": "Update a sales channel's configuration", "tags": [ "Sales Channels" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "channelTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "tagged" ] }, "channelTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "mode" ] }, "pricingConfig": { "type": "object", "properties": { "showMemberPricing": { "type": "boolean" }, "showOriginalPrice": { "type": "boolean" }, "includeFeesInPrice": { "type": "boolean" } } }, "customerConfig": { "type": "object", "properties": { "requireLogin": { "type": "boolean" }, "allowGuestCheckout": { "type": "boolean" }, "collectPhone": { "type": "boolean" }, "collectAddress": { "type": "boolean" } } }, "customerFacing": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "subdomain": { "type": "string", "minLength": 1, "maxLength": 63 }, "customDomain": { "type": "string", "minLength": 1, "maxLength": 255 }, "allowedOrigins": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^https?:\\/\\/[*a-zA-Z0-9.:-]+$" } ] } }, "magicLinkBaseUrl": { "type": "string", "format": "uri" }, "partnerIdentity": { "type": "object", "properties": { "issuer": { "type": "string", "minLength": 1 }, "publicKeyPem": { "type": "string", "minLength": 1 }, "algorithm": { "type": "string", "enum": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512" ] } }, "required": [ "issuer", "publicKeyPem", "algorithm" ] } } }, "reservationTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 3600 }, "checkoutTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 1800 }, "receivingAccountId": { "type": "string", "minLength": 1 }, "feeProfileId": { "type": [ "string", "null" ], "minLength": 1 }, "paymentProviderId": { "type": [ "string", "null" ], "minLength": 1 }, "themeId": { "type": [ "string", "null" ], "pattern": "^sct_[a-zA-Z0-9]+$" }, "isActive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Sales channel updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete sales channel", "operationId": "deleteSalesChannel", "description": "Soft-delete a sales channel", "tags": [ "Sales Channels" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Sales channel deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSalesChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/keys": { "post": { "summary": "Issue channel key", "operationId": "issueSalesChannelKey", "description": "Issue a publishable (tlpk_) or secret (tlsk_) key for the channel. Secret key material is returned exactly once.", "tags": [ "Keys" ], "x-sdk-method": "issue", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keyType": { "type": "string", "enum": [ "publishable", "secret" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "keyType", "name" ] } } } }, "responses": { "201": { "description": "Channel key issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueSalesChannelKeyResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List channel keys", "operationId": "listSalesChannelKeys", "description": "List the channel's keys. Secret key material is never returned; publishable keys are public by design.", "tags": [ "Keys" ], "x-sdk-method": "list", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Channel keys retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSalesChannelKeysResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/keys/{keyId}/revoke": { "post": { "summary": "Revoke channel key", "operationId": "revokeSalesChannelKey", "description": "Revoke a channel key so it can no longer authenticate", "tags": [ "Keys" ], "x-sdk-method": "revoke", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "keyId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Channel key revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSalesChannelKeyResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/listings": { "post": { "summary": "List event on channel", "operationId": "createSalesChannelListing", "description": "List an event on the channel, optionally within a sale window. An event is never published globally - it is listed on channels.", "tags": [ "Listings" ], "x-sdk-method": "create", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 }, "saleStartsAt": { "type": "string", "example": "2026-02-01T09:00:00Z", "description": "Sale window start (ISO 8601); omit for open-ended" }, "saleEndsAt": { "type": "string", "example": "2026-06-01T00:00:00Z", "description": "Sale window end (ISO 8601); omit for open-ended" } }, "required": [ "eventId" ] } } } }, "responses": { "201": { "description": "Listing created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelListingResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List channel listings", "operationId": "listSalesChannelListings", "description": "List the events listed on the channel", "tags": [ "Listings" ], "x-sdk-method": "list", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Listings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSalesChannelListingsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/listings/{listingId}": { "delete": { "summary": "Remove channel listing", "operationId": "deleteSalesChannelListing", "description": "Remove an event listing from the channel", "tags": [ "Listings" ], "x-sdk-method": "delete", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "listingId", "in": "path" } ], "responses": { "200": { "description": "Listing removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSalesChannelListingResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/carts": { "post": { "summary": "Create staff cart", "operationId": "createStaffCart", "description": "Create a cart on the channel as a staff actor. Trusted actors may act on behalf of a customer they have looked up.", "tags": [ "Carts" ], "x-sdk-method": "create", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "201": { "description": "Cart created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/carts/{cartId}": { "get": { "summary": "Get staff cart", "operationId": "getStaffCart", "description": "Get a cart with its items", "tags": [ "Carts" ], "x-sdk-method": "get", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Cart retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/carts/{cartId}/items": { "post": { "summary": "Add staff cart item", "operationId": "addStaffCartItem", "description": "Add an item to the cart, taking a real inventory reservation", "tags": [ "Carts" ], "x-sdk-method": "addItem", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventOccurrenceId": { "type": "string", "minLength": 1 }, "categoryId": { "type": "string", "minLength": 1 }, "ticketTypeId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 50 }, "eventLayoutAreaId": { "type": "string", "minLength": 1 }, "eventLayoutSeatIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 } }, "required": [ "eventOccurrenceId", "categoryId", "ticketTypeId" ] } } } }, "responses": { "201": { "description": "Item added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/carts/{cartId}/items/{itemId}": { "delete": { "summary": "Remove staff cart item", "operationId": "removeStaffCartItem", "description": "Remove an item from the cart, releasing its reservation", "tags": [ "Carts" ], "x-sdk-method": "removeItem", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "itemId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Item removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales-channels/{channelId}/carts/{cartId}/checkout": { "post": { "summary": "Checkout staff cart", "operationId": "checkoutStaffCart", "description": "Convert the cart into an order. Manual discounts require the orders.applydiscount permission.", "tags": [ "Carts" ], "x-sdk-method": "checkout", "x-parent-resource": "Sales Channels", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "customerNotes": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": {} }, "discount": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0 }, "percent": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "label": { "type": "string", "maxLength": 100 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ] } } } } } }, "responses": { "200": { "description": "Cart checked out successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCheckoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/presale-codes": { "post": { "summary": "Create presale code", "operationId": "createPresaleCode", "description": "Create a shareable presale code that grants a benefit on redemption", "tags": [ "Presale Codes" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 3, "maxLength": 50, "pattern": "^[a-zA-Z0-9-]+$" }, "benefit": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+([.-][a-z0-9]+)*$" }, "channelId": { "type": "string", "minLength": 1 }, "maxRedemptions": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": "string", "example": "2026-03-01T00:00:00Z", "description": "Code validity end (ISO 8601); omit for no expiry" }, "benefitExpiresAt": { "type": "string", "example": "2026-06-01T00:00:00Z", "description": "When the granted benefit lapses (ISO 8601); omit for no expiry" } }, "required": [ "accountId", "code", "benefit" ] } } } }, "responses": { "201": { "description": "Presale code created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresaleCodeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List presale codes", "operationId": "listPresaleCodes", "description": "List the organisation's presale codes visible to the caller", "tags": [ "Presale Codes" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Presale codes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPresaleCodesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/presale-codes/{codeId}/deactivate": { "post": { "summary": "Deactivate presale code", "operationId": "deactivatePresaleCode", "description": "Deactivate a presale code so it can no longer be redeemed", "tags": [ "Presale Codes" ], "x-sdk-method": "deactivate", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "codeId", "in": "path" } ], "responses": { "200": { "description": "Presale code deactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresaleCodeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/fee-profiles": { "post": { "summary": "Create fee profile", "operationId": "createFeeProfile", "description": "Create an org-level fee configuration that sales channels can reference", "tags": [ "Fee Profiles" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "serviceFeeEnabled": { "type": "boolean" }, "serviceFeePercent": { "type": "number", "minimum": 0, "maximum": 1 }, "serviceFeeFixed": { "type": "integer", "minimum": 0 }, "serviceFeeLabel": { "type": "string", "maxLength": 100 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Fee profile created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeProfileResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List fee profiles", "operationId": "listFeeProfiles", "description": "List the organisation's fee profiles", "tags": [ "Fee Profiles" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Fee profiles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFeeProfilesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/fee-profiles/{profileId}": { "get": { "summary": "Get fee profile", "operationId": "getFeeProfile", "description": "Get a fee profile by ID", "tags": [ "Fee Profiles" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Fee profile retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeProfileResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update fee profile", "operationId": "updateFeeProfile", "description": "Update a fee profile", "tags": [ "Fee Profiles" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "profileId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "serviceFeeEnabled": { "type": "boolean" }, "serviceFeePercent": { "type": "number", "minimum": 0, "maximum": 1 }, "serviceFeeFixed": { "type": "integer", "minimum": 0 }, "serviceFeeLabel": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Fee profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeProfileResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete fee profile", "operationId": "deleteFeeProfile", "description": "Soft-delete a fee profile", "tags": [ "Fee Profiles" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "profileId", "in": "path" } ], "responses": { "200": { "description": "Fee profile deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFeeProfileResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/listings": { "get": { "summary": "List active listings", "operationId": "listSalesListings", "description": "What is on sale through this channel right now. The channel is resolved from the key, never from a parameter.", "tags": [ "Sales Listings" ], "x-sdk-method": "list", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Listings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSalesListingsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-auth/magic-link": { "post": { "summary": "Request magic link", "operationId": "requestSalesMagicLink", "description": "Start a magic-link sign-in for a customer. Always reports success - account existence is never revealed.", "tags": [ "Sales Customer Auth" ], "x-sdk-method": "magicLink", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "minLength": 5, "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Magic link request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesMagicLinkResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-tokens": { "post": { "summary": "Exchange identity proof for customer token", "operationId": "createSalesCustomerToken", "description": "Exchange an identity proof (magic-link code or partner assertion) for a short-lived customer token bound to this channel. Identity is exchanged, never asserted.", "tags": [ "Sales Customer Tokens" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "proof": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "magic_link" ] }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "code" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partner_assertion" ] }, "assertion": { "type": "string", "minLength": 1 } }, "required": [ "type", "assertion" ] } ] } }, "required": [ "proof" ] } } } }, "responses": { "200": { "description": "Customer token issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerTokenResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts": { "post": { "summary": "Create cart", "operationId": "createSalesCart", "description": "Create a cart on this channel. Customer identity comes only from a verified customer token, never from the body.", "tags": [ "Sales Carts" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": {} } } } } } }, "responses": { "201": { "description": "Cart created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}": { "get": { "summary": "Get cart", "operationId": "getSalesCart", "description": "Get a cart with its items", "tags": [ "Sales Carts" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "responses": { "200": { "description": "Cart retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/items": { "post": { "summary": "Add cart item", "operationId": "addSalesCartItem", "description": "Add an item to the cart, taking a real inventory reservation with the channel's TTL", "tags": [ "Sales Carts" ], "x-sdk-method": "addItem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventOccurrenceId": { "type": "string", "minLength": 1 }, "categoryId": { "type": "string", "minLength": 1 }, "ticketTypeId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 50 }, "eventLayoutAreaId": { "type": "string", "minLength": 1 }, "eventLayoutSeatIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 } }, "required": [ "eventOccurrenceId", "categoryId", "ticketTypeId" ] } } } }, "responses": { "201": { "description": "Item added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/items/{itemId}": { "delete": { "summary": "Remove cart item", "operationId": "removeSalesCartItem", "description": "Remove an item from the cart, releasing its reservation", "tags": [ "Sales Carts" ], "x-sdk-method": "removeItem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "itemId", "in": "path" } ], "responses": { "200": { "description": "Item removed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCartResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/carts/{cartId}/checkout": { "post": { "summary": "Checkout cart", "operationId": "checkoutSalesCart", "description": "Convert the cart into an order. Returns an order access token for possession-based guest access (confirmation page, payment status polling).", "tags": [ "Sales Carts" ], "x-sdk-method": "checkout", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "cartId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerNotes": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": {} }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "minLength": 5, "maxLength": 50 }, "marketingConsent": { "type": "boolean" } }, "required": [ "email" ] } } } } } }, "responses": { "200": { "description": "Cart checked out successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCheckoutResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/my-orders": { "get": { "summary": "List my orders", "operationId": "listMySalesOrders", "description": "The verified customer's own orders. Requires a customer token - orders cannot be listed with key or possession credentials alone.", "tags": [ "Sales My Orders" ], "x-sdk-method": "list", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMySalesOrdersResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}": { "get": { "summary": "Get order", "operationId": "getSalesOrder", "description": "Get an order on this channel. Access requires a secret key (own channel), an X-Order-Access-Token header (guest possession) or a customer token (own orders).", "tags": [ "Sales Orders" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSalesOrderResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/passes/{passId}/ticket.pdf": { "get": { "summary": "Download a ticket PDF", "operationId": "getSalesOrderTicketPdf", "description": "Render and stream a pass as a PDF ticket (application/pdf) for the holder. Order-access gated. Browsers fetch this directly rather than through the typed SDK.", "tags": [ "Sales Orders" ], "x-sdk-method": "ticketPdf", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "example": "ord_abc123xyz789" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string", "example": "pas_7D6SYiF0oExsH1aYwtsv" }, "required": true, "name": "passId", "in": "path" } ], "responses": { "200": { "description": "PDF ticket (application/pdf)" }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/payments": { "post": { "summary": "Create order payment", "operationId": "createSalesOrderPayment", "description": "Initiate payment for the order's outstanding balance through the channel's payment provider", "tags": [ "Sales Order Payments" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "online_card", "online_bank_transfer", "online_wallet" ] }, "returnUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Payment initiated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSalesOrderPaymentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/orders/{orderId}/refund-requests": { "post": { "summary": "Request refund or exchange", "operationId": "createSalesOrderRefundRequest", "description": "File a refund or exchange request for the order within the resolved refund policy. Requester identity is derived from the credential, never from the body.", "tags": [ "Sales Refund Requests" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orderId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refund", "exchange" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Refund request created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSalesRefundRequestResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customers": { "post": { "summary": "Create customer", "operationId": "createSalesCustomer", "description": "Provenance-scoped channel CRM (secret keys only). Reuses the org's existing record for the email and grants the channel access; there is no list or search.", "tags": [ "Sales Customers" ], "x-sdk-method": "create", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "maxLength": 255 }, "lastName": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 }, "marketingConsent": { "type": "boolean" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customers/{customerId}": { "get": { "summary": "Get customer", "operationId": "getSalesCustomer", "description": "Get a customer the channel holds an access grant for (created through it, or who bought through it)", "tags": [ "Sales Customers" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update customer", "operationId": "updateSalesCustomer", "description": "Update a customer the channel holds an access grant for. The update surface is deliberately small - email changes go through the org's staff.", "tags": [ "Sales Customers" ], "x-sdk-method": "update", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "customerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 255 }, "lastName": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/presale-codes/redeem": { "post": { "summary": "Redeem presale code", "operationId": "redeemSalesPresaleCode", "description": "A verified customer redeems a presale code for its benefit; gated pricing unlocks immediately. Requires a customer token.", "tags": [ "Sales Presale Codes" ], "x-sdk-method": "redeem", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Presale code redeemed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemSalesPresaleCodeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/customer-tokens/refresh": { "post": { "summary": "Refresh a customer token", "operationId": "refreshSalesCustomerToken", "description": "Re-signs a still-valid customer token (presented via X-Customer-Token) for a fresh 30 minutes, carrying the original 24-hour absolute ceiling forward. Once the ceiling passes the customer must re-authenticate.", "tags": [ "Sales Customer Tokens" ], "x-sdk-method": "refresh", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Customer token refreshed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCustomerTokenResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/channel": { "get": { "summary": "Resolve a channel by domain", "operationId": "resolveSalesChannel", "description": "Public tenant resolution for hosted surfaces: maps a hostname (the channel's configured subdomain or custom domain) to its channel summary and publishable key. No authentication; rate-limited.", "tags": [ "Sales" ], "x-sdk-method": "resolveChannel", "x-tl-surface": "sales", "parameters": [ { "schema": { "type": "string", "example": "tickets.acmevenue.com", "description": "The hostname to resolve" }, "required": true, "description": "The hostname to resolve", "name": "domain", "in": "query" } ], "responses": { "200": { "description": "Channel resolved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesResolveChannelResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/events/{eventId}": { "get": { "summary": "Get event catalogue detail", "operationId": "getSalesEvent", "description": "Catalogue detail for an event listed on this channel: occurrences with their priced ticket-type offers. Benefit-gated types are included only when the request carries a customer token holding the benefit. Returns 404 if the event is not listed on this channel.", "tags": [ "Sales" ], "x-sdk-method": "get", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "parameters": [ { "schema": { "type": "string", "example": "evt_abc123", "description": "The event ID" }, "required": true, "description": "The event ID", "name": "eventId", "in": "path" } ], "responses": { "200": { "description": "Event detail retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesEventDetailResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/sales/theme": { "get": { "summary": "Get channel theme", "operationId": "getSalesTheme", "description": "The channel's resolved (inheritance-merged) theme for SSR injection. Returns 404 if the channel has neither its own theme nor an organisation base theme.", "tags": [ "Sales" ], "x-sdk-method": "getTheme", "x-tl-surface": "sales", "security": [ { "channelKey": [] } ], "responses": { "200": { "description": "Theme retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/themes": { "get": { "summary": "List themes", "operationId": "listThemes", "description": "List all branding/design themes for the organisation", "tags": [ "Themes" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Themes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeListResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create theme", "operationId": "createTheme", "description": "Create a new branding/design theme", "tags": [ "Themes" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Midnight", "description": "Theme name" }, "description": { "type": "string", "example": "Dark theme for evening events", "description": "Theme description" }, "extendsThemeId": { "type": "string", "pattern": "^sct_[a-zA-Z0-9]+$", "example": "sct_base123", "description": "Parent theme this theme inherits from" }, "isBaseTheme": { "type": "boolean", "default": false, "example": false, "description": "Whether this is the organisation's fallback base theme" }, "isActive": { "type": "boolean", "default": true, "example": true }, "brand": { "$ref": "#/components/schemas/ThemeBrandInput" }, "colors": { "$ref": "#/components/schemas/ThemeColorsInput" }, "typography": { "$ref": "#/components/schemas/ThemeTypographyInput" }, "shape": { "$ref": "#/components/schemas/ThemeShapeInput" }, "design": { "$ref": "#/components/schemas/ThemeDesignInput" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Theme created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/themes/{id}": { "get": { "summary": "Get theme", "operationId": "getTheme", "description": "Get a specific theme by ID", "tags": [ "Themes" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sct_[a-zA-Z0-9]+$", "example": "sct_abc123", "description": "Theme ID" }, "required": true, "description": "Theme ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Theme retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update theme", "operationId": "updateTheme", "description": "Update an existing theme", "tags": [ "Themes" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sct_[a-zA-Z0-9]+$", "example": "sct_abc123", "description": "Theme ID" }, "required": true, "description": "Theme ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "extendsThemeId": { "type": [ "string", "null" ], "pattern": "^sct_[a-zA-Z0-9]+$" }, "isBaseTheme": { "type": "boolean" }, "isActive": { "type": "boolean" }, "brand": { "$ref": "#/components/schemas/ThemeBrandInput" }, "colors": { "$ref": "#/components/schemas/ThemeColorsInput" }, "typography": { "$ref": "#/components/schemas/ThemeTypographyInput" }, "shape": { "$ref": "#/components/schemas/ThemeShapeInput" }, "design": { "allOf": [ { "$ref": "#/components/schemas/ThemeDesignInput" }, { "type": [ "object", "null" ] } ] } } } } } }, "responses": { "200": { "description": "Theme updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete theme", "operationId": "deleteTheme", "description": "Soft-delete a theme", "tags": [ "Themes" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sct_[a-zA-Z0-9]+$", "example": "sct_abc123", "description": "Theme ID" }, "required": true, "description": "Theme ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Theme deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/themes/{id}/resolved": { "get": { "summary": "Get resolved theme", "operationId": "getResolvedTheme", "description": "Get a theme with its inheritance chain deep-merged (parent tokens overridden by the child)", "tags": [ "Themes" ], "x-sdk-method": "resolved", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sct_[a-zA-Z0-9]+$", "example": "sct_abc123", "description": "Theme ID" }, "required": true, "description": "Theme ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Resolved theme retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedThemeResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/passes/{barcode}/redeem": { "post": { "summary": "Redeem a pass", "operationId": "redeemPass", "description": "Redeem a pass by its barcode at a gate. Idempotent under an Idempotency-Key header. Returns an outcome of valid, duplicate, or void. (Basic implementation: status + limit only; the full rules engine is part of the scanning/Go stream.)", "tags": [ "Entitlements" ], "x-sdk-method": "redeem", "x-parent-resource": "passes", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tkt_oL3OhU2Zu6Xgv4pf3txvOCpDYDkFXdgQ", "description": "The opaque pass barcode (QR payload) being redeemed" }, "required": true, "description": "The opaque pass barcode (QR payload) being redeemed", "name": "barcode", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "dvid_abc123", "description": "Scanning device id (optional; devices arrive with the Go stream)" }, "location": { "type": "string", "example": "Main Gate", "description": "Redemption point label (optional)" }, "idempotencyKey": { "type": "string", "example": "scan_8f2c…", "description": "Idempotency key; replays return the original outcome. May also be sent as the Idempotency-Key header." } } } } } }, "responses": { "200": { "description": "Redemption processed (see outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemPassResult" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/ticket-templates": { "get": { "summary": "List ticket templates", "operationId": "listTicketTemplates", "description": "List the organisation's ticket/pass templates (the designer layouts).", "tags": [ "Ticket Templates" ], "x-sdk-method": "list", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "eventId", "in": "query" } ], "responses": { "200": { "description": "Templates retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketTemplatesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create ticket template", "operationId": "createTicketTemplate", "description": "Create a ticket/pass template. layout is the renderer-agnostic block model.", "tags": [ "Ticket Templates" ], "x-sdk-method": "create", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Standard eticket" }, "type": { "type": "string", "enum": [ "ticket", "eticket", "label", "receipt" ], "example": "eticket" }, "description": { "type": [ "string", "null" ] }, "layout": { "type": "object", "properties": { "page": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "background": { "type": "object", "properties": { "color": { "type": "string" } }, "additionalProperties": {} } }, "required": [ "width", "height" ], "additionalProperties": {} }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "qr", "barcode", "image", "rect" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "id", "type", "x", "y", "width", "height" ], "additionalProperties": {} } } }, "required": [ "page", "blocks" ], "description": "Renderer-agnostic ticket layout: page + positioned blocks (points)." }, "scopeEventId": { "type": [ "string", "null" ], "example": "evt_yf0BrApW" }, "scopeTicketTypeId": { "type": [ "string", "null" ] }, "scopeChannelId": { "type": [ "string", "null" ] }, "themeId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "isDefault": { "type": "boolean" }, "accountId": { "type": [ "string", "null" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketTemplateResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/ticket-templates/{id}": { "get": { "summary": "Get ticket template", "operationId": "getTicketTemplate", "description": "Get a ticket/pass template by id.", "tags": [ "Ticket Templates" ], "x-sdk-method": "get", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "tpl_abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketTemplateResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update ticket template", "operationId": "updateTicketTemplate", "description": "Update a ticket/pass template. Saving a new layout bumps its version.", "tags": [ "Ticket Templates" ], "x-sdk-method": "update", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "tpl_abc123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "ticket", "eticket", "label", "receipt" ], "example": "eticket" }, "description": { "type": [ "string", "null" ] }, "layout": { "type": "object", "properties": { "page": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "background": { "type": "object", "properties": { "color": { "type": "string" } }, "additionalProperties": {} } }, "required": [ "width", "height" ], "additionalProperties": {} }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "qr", "barcode", "image", "rect" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "id", "type", "x", "y", "width", "height" ], "additionalProperties": {} } } }, "required": [ "page", "blocks" ], "description": "Renderer-agnostic ticket layout: page + positioned blocks (points)." }, "scopeEventId": { "type": [ "string", "null" ] }, "scopeTicketTypeId": { "type": [ "string", "null" ] }, "scopeChannelId": { "type": [ "string", "null" ] }, "themeId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Template updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketTemplateResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete ticket template", "operationId": "deleteTicketTemplate", "description": "Soft-delete a ticket/pass template.", "tags": [ "Ticket Templates" ], "x-sdk-method": "delete", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "example": "tpl_abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTicketTemplateResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/orders/{orderId}/passes/{passId}/print": { "post": { "summary": "Print a pass to a device", "operationId": "printPass", "description": "Render the pass to its canonical SVG and dispatch it as a print job to a printer device. Returns the device command id (poll the devices command for status).", "tags": [ "Orders" ], "x-sdk-method": "printPass", "x-parent-resource": "Orders", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "orderId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "passId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerId": { "type": "string" }, "type": { "type": "string", "enum": [ "print.ticket", "print.label", "print.receipt" ] } }, "required": [ "printerId" ] } } } }, "responses": { "201": { "description": "Print job dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "commandId": { "type": "string" } }, "required": [ "commandId" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan-configs": { "post": { "summary": "Create a scan configuration", "operationId": "createScanConfig", "description": "Create a scanner scope (events + entitlement/gate/time filters + allowed operations). Delegation-gated: the author must hold entitlements.redeem on the account.", "tags": [ "Scan Configs" ], "x-sdk-method": "create", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": "array", "items": { "type": "string" } }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" } }, "required": [ "accountId", "name", "eventFilter", "allowedKinds" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanConfig": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "accountId": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": [ "object", "null" ], "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validFrom": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "accountId", "eventFilter", "entitlementFilter", "allowedKinds", "gates", "validFrom", "validUntil", "createdAt", "updatedAt" ] } }, "required": [ "scanConfig" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List scan configurations", "operationId": "listScanConfigs", "tags": [ "Scan Configs" ], "x-sdk-method": "list", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Scan configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanConfigs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "accountId": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": [ "object", "null" ], "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validFrom": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "accountId", "eventFilter", "entitlementFilter", "allowedKinds", "gates", "validFrom", "validUntil", "createdAt", "updatedAt" ] } } }, "required": [ "scanConfigs" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan-configs/{configId}": { "get": { "summary": "Get a scan configuration", "operationId": "getScanConfig", "tags": [ "Scan Configs" ], "x-sdk-method": "get", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "configId", "in": "path" } ], "responses": { "200": { "description": "Scan configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanConfig": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "accountId": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": [ "object", "null" ], "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validFrom": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "accountId", "eventFilter", "entitlementFilter", "allowedKinds", "gates", "validFrom", "validUntil", "createdAt", "updatedAt" ] } }, "required": [ "scanConfig" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update a scan configuration", "operationId": "updateScanConfig", "tags": [ "Scan Configs" ], "x-sdk-method": "update", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "configId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": "array", "items": { "type": "string" } }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanConfig": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "accountId": { "type": "string" }, "eventFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "events", "occurrences" ] }, "eventIds": { "type": "array", "items": { "type": "string" } }, "occurrenceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] }, "entitlementFilter": { "type": [ "object", "null" ], "properties": { "types": { "type": "array", "items": { "type": "string" } }, "ticketTypeIds": { "type": "array", "items": { "type": "string" } }, "entitlementIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "allowedKinds": { "type": "array", "items": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] } }, "gates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validFrom": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "deviceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "accountId", "eventFilter", "entitlementFilter", "allowedKinds", "gates", "validFrom", "validUntil", "createdAt", "updatedAt" ] } }, "required": [ "scanConfig" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete a scan configuration", "operationId": "deleteScanConfig", "tags": [ "Scan Configs" ], "x-sdk-method": "delete", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "configId", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan-configs/{configId}/devices": { "put": { "summary": "Assign scanner devices to a configuration", "operationId": "setScanConfigDevices", "description": "Replace the set of scanner devices driven by this config. A device has at most one active config.", "tags": [ "Scan Configs" ], "x-sdk-method": "setDevices", "x-parent-resource": "Scan Configs", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "configId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "deviceIds" ] } } } }, "responses": { "200": { "description": "Assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "deviceIds" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan/config": { "get": { "summary": "Get the device scan scope", "operationId": "getScanConfigForDevice", "description": "The calling scanner device’s resolved configuration (scope + allowed operations). Device JWT only.", "tags": [ "Scan" ], "x-sdk-method": "config", "x-parent-resource": "Scan", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Scan config", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanConfig": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "eventFilter": { "type": "object", "additionalProperties": {} }, "entitlementFilter": { "type": [ "object", "null" ], "additionalProperties": {} }, "allowedKinds": { "type": "array", "items": { "type": "string" } }, "gates": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validFrom": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "configVersion": { "type": "string" } }, "required": [ "id", "name", "eventFilter", "entitlementFilter", "allowedKinds", "gates", "validFrom", "validUntil", "configVersion" ] } }, "required": [ "scanConfig" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan/manifest": { "get": { "summary": "Get the offline validation dataset", "operationId": "getScanManifest", "description": "The entitlements in scope, as a cursored delta (pass ?since= the prior cursor). Device JWT only.", "tags": [ "Scan" ], "x-sdk-method": "manifest", "x-parent-resource": "Scan", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" } ], "responses": { "200": { "description": "Manifest delta", "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlements": { "type": "array", "items": { "type": "object", "properties": { "barcode": { "type": "string" }, "passId": { "type": "string" }, "entitlementId": { "type": "string" }, "occurrenceId": { "type": [ "string", "null" ] }, "holderName": { "type": [ "string", "null" ] }, "ticketTypeName": { "type": "string" }, "type": { "type": "string" }, "seatLabel": { "type": [ "string", "null" ] }, "orderRef": { "type": "string" }, "passStatus": { "type": "string" }, "entitlementStatus": { "type": "string" }, "redemptionLimit": { "type": [ "number", "null" ] }, "redemptionCount": { "type": "number" }, "rulesSummary": {}, "updatedAt": { "type": "string" } }, "required": [ "barcode", "passId", "entitlementId", "occurrenceId", "holderName", "ticketTypeName", "type", "seatLabel", "orderRef", "passStatus", "entitlementStatus", "redemptionLimit", "redemptionCount", "updatedAt" ] } }, "redemptions": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "nextCursor": { "type": "string" }, "hasMore": { "type": "boolean" }, "full": { "type": "boolean" } }, "required": [ "entitlements", "redemptions", "nextCursor", "hasMore", "full" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scan/operations": { "post": { "summary": "Submit scan operations", "operationId": "submitScanOperations", "description": "Batch of ScanOperations - applied in occurredAt order, idempotent on opId, duplicates recorded + noted. Device JWT only.", "tags": [ "Scan" ], "x-sdk-method": "operations", "x-parent-resource": "Scan", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "opId": { "type": "string" }, "kind": { "type": "string", "enum": [ "validate", "redeem", "reverse" ] }, "passBarcode": { "type": "string" }, "entitlementId": { "type": "string" }, "occurredAt": { "type": "string" }, "seq": { "type": "number" }, "gate": { "type": "string" }, "reverseOf": { "type": "string" }, "originDeviceId": { "type": "string" }, "locationId": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "device", "user" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "hopPath": { "type": "array", "items": { "type": "string" } } }, "required": [ "opId", "kind", "passBarcode", "occurredAt" ] } } }, "required": [ "operations" ] } } } }, "responses": { "200": { "description": "Per-operation results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "opId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "valid", "duplicate", "rejected", "reversed" ] }, "reason": { "type": "string" }, "holderName": { "type": [ "string", "null" ] }, "ticketTypeName": { "type": "string" }, "seatLabel": { "type": [ "string", "null" ] }, "orderRef": { "type": "string" }, "entitlement": { "type": "object", "additionalProperties": {} }, "conflict": { "type": "object", "additionalProperties": {} }, "redemption": { "type": "object", "additionalProperties": {} } }, "required": [ "opId", "outcome" ] } } }, "required": [ "results" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/scans": { "get": { "summary": "List scans (staff reporting)", "operationId": "listScans", "description": "Redemption/scan history, account-filtered, faceted by occurrence/event/device/status.", "tags": [ "Scans" ], "x-sdk-method": "list", "x-parent-resource": "Scans", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "occurrenceId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "eventId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "deviceId", "in": "query" }, { "schema": { "type": "string", "enum": [ "validated", "redeemed", "rejected", "reversed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Scans", "content": { "application/json": { "schema": { "type": "object", "properties": { "scans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "entitlementId": { "type": "string" }, "passId": { "type": "string" }, "barcode": { "type": "string" }, "holderName": { "type": [ "string", "null" ] }, "ticketTypeName": { "type": "string" }, "seatLabel": { "type": [ "string", "null" ] }, "occurrenceId": { "type": [ "string", "null" ] }, "gate": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "occurredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "entitlementId", "passId", "barcode", "holderName", "ticketTypeName", "seatLabel", "occurrenceId", "gate", "deviceId", "reason", "occurredAt", "createdAt" ] } } }, "required": [ "scans" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/redemptions/{redemptionId}/reverse": { "post": { "summary": "Reverse a redemption", "operationId": "reverseRedemption", "description": "Supervisor undo of a mistaken scan: the redemption becomes reversed and the entitlement gets its consumption back.", "tags": [ "Scans" ], "x-sdk-method": "reverse", "x-parent-resource": "Scans", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "redemptionId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Reversed", "content": { "application/json": { "schema": { "type": "object", "properties": { "redemption": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "entitlementId": { "type": "string" }, "reversedAt": { "type": [ "string", "null" ] }, "reversalReason": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "entitlementId", "reversedAt", "reversalReason" ] } }, "required": [ "redemption" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/assets": { "get": { "summary": "List assets", "operationId": "listAssets", "description": "List the organisation's tracked assets (uploads + renders). Filter by purpose/owner.", "tags": [ "Assets" ], "x-sdk-method": "list", "x-parent-resource": "assets", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "purpose", "in": "query" }, { "schema": { "type": "string", "maxLength": 48 }, "required": false, "name": "ownerType", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "ownerId", "in": "query" }, { "schema": { "type": "string", "maxLength": 24 }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Assets retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAssetsResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Upload an asset", "operationId": "uploadAsset", "description": "Upload a file (multipart/form-data; field \"file\") to central storage and track it. Metadata fields (purpose, ownerType, ownerId, accountId, visibility, cdn) accompany the file.", "tags": [ "Assets" ], "x-sdk-method": "upload", "x-parent-resource": "assets", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "purpose": { "type": "string", "enum": [ "event_image", "organisation_logo", "account_logo", "user_avatar", "ticket_template_asset", "rendered_pass", "rendered_receipt", "export", "other" ] }, "ownerType": { "type": "string", "maxLength": 48 }, "ownerId": { "type": "string", "maxLength": 64 }, "accountId": { "type": "string", "maxLength": 24 }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "cdn": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } } } } }, "responses": { "201": { "description": "Asset uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/assets/{id}": { "get": { "summary": "Get an asset", "operationId": "getAsset", "description": "Get a tracked asset by id.", "tags": [ "Assets" ], "x-sdk-method": "get", "x-parent-resource": "assets", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ast_[A-Za-z0-9]+$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Asset retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete an asset", "operationId": "deleteAsset", "description": "Soft-delete a tracked asset (bytes are left in storage for later GC).", "tags": [ "Assets" ], "x-sdk-method": "delete", "x-parent-resource": "assets", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^ast_[A-Za-z0-9]+$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Asset deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAssetResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/pairing": { "post": { "summary": "Start device pairing", "operationId": "startDevicePairing", "description": "A device begins pairing and receives a user code + device code (unauthenticated).", "tags": [ "Device Pairing" ], "x-sdk-method": "start", "x-parent-resource": "Device Pairing", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relay", "scanner", "kiosk", "signage" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "platform": { "type": "object", "properties": { "os": { "type": "string", "maxLength": 100 }, "osVersion": { "type": "string", "maxLength": 100 }, "appVersion": { "type": "string", "maxLength": 50 }, "hostname": { "type": "string", "maxLength": 255 }, "arch": { "type": "string", "maxLength": 50 } } } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Pairing started", "content": { "application/json": { "schema": { "type": "object", "properties": { "pairingId": { "type": "string" }, "userCode": { "type": "string" }, "deviceCode": { "type": "string" }, "verificationUrl": { "type": "string" }, "verificationUrlComplete": { "type": "string" }, "expiresAt": { "type": "string" }, "pollIntervalSeconds": { "type": "number" } }, "required": [ "pairingId", "userCode", "deviceCode", "verificationUrl", "verificationUrlComplete", "expiresAt", "pollIntervalSeconds" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/pairing/{pairingId}": { "get": { "summary": "Poll device pairing status", "operationId": "getDevicePairing", "description": "The device polls pairing status, authenticated by its device code (query or X-Device-Code header).", "tags": [ "Device Pairing" ], "x-sdk-method": "getStatus", "x-parent-resource": "Device Pairing", "x-tl-surface": "backstage", "parameters": [ { "schema": { "type": "string", "pattern": "^dvpair_[a-zA-Z0-9]+$" }, "required": true, "name": "pairingId", "in": "path" } ], "responses": { "200": { "description": "Pairing status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "claimedBy": { "type": "object", "properties": { "organisationId": { "type": "string" }, "organisationName": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "organisationId" ] }, "grantSummary": { "type": "string" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/pairing/claim": { "post": { "summary": "Claim a device pairing", "operationId": "claimDevicePairing", "description": "Staff claim a pending pairing for their organisation, naming the device and granting roles.", "tags": [ "Device Pairing" ], "x-sdk-method": "claim", "x-parent-resource": "Device Pairing", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userCode": { "type": "string", "minLength": 3, "maxLength": 16 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 24 }, "locationId": { "type": "string", "maxLength": 24 }, "accountRoles": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 24 }, "roleId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "accountId", "roleId" ] }, "minItems": 1 } }, "required": [ "userCode", "name", "accountId", "accountRoles" ] } } } }, "responses": { "200": { "description": "Pairing claimed", "content": { "application/json": { "schema": { "type": "object", "properties": { "pairingId": { "type": "string" }, "status": { "type": "string" }, "deviceInfo": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ] } }, "required": [ "pairingId", "status", "deviceInfo" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/pairing/{pairingId}/confirm": { "post": { "summary": "Confirm device adoption", "operationId": "confirmDevicePairing", "description": "The device confirms adoption and receives its id + one-time secret (device-code auth).", "tags": [ "Device Pairing" ], "x-sdk-method": "confirm", "x-parent-resource": "Device Pairing", "x-tl-surface": "backstage", "parameters": [ { "schema": { "type": "string", "pattern": "^dvpair_[a-zA-Z0-9]+$" }, "required": true, "name": "pairingId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Pairing confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "type": "string" }, "deviceSecret": { "type": "string" } }, "required": [ "deviceId", "deviceSecret" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/pairing/{pairingId}/reject": { "post": { "summary": "Reject device adoption", "operationId": "rejectDevicePairing", "description": "The device rejects adoption; the pairing is invalidated (device-code auth).", "tags": [ "Device Pairing" ], "x-sdk-method": "reject", "x-parent-resource": "Device Pairing", "x-tl-surface": "backstage", "parameters": [ { "schema": { "type": "string", "pattern": "^dvpair_[a-zA-Z0-9]+$" }, "required": true, "name": "pairingId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Pairing rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/token": { "post": { "summary": "Mint a device token", "operationId": "issueDeviceToken", "description": "Exchange (deviceId, deviceSecret) for a short-lived device JWT.", "tags": [ "Device Auth" ], "x-sdk-method": "issueToken", "x-parent-resource": "Device Auth", "x-tl-surface": "backstage", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "deviceSecret": { "type": "string", "minLength": 1 } }, "required": [ "deviceId", "deviceSecret" ] } } } }, "responses": { "200": { "description": "Device token", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "expiresInSeconds": { "type": "number" } }, "required": [ "token", "expiresInSeconds" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/jwks": { "get": { "summary": "Device JWKS", "operationId": "getDeviceJwks", "description": "Public keys for offline Local Command Token verification by relays.", "tags": [ "Device Auth" ], "x-sdk-method": "jwks", "x-parent-resource": "Device Auth", "x-tl-surface": "backstage", "responses": { "200": { "description": "JWKS", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "version": { "type": "number" } }, "required": [ "keys", "version" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me": { "get": { "summary": "Get own device record", "operationId": "getDeviceMe", "description": "The device fetches its own record, granted roles and local config (device JWT).", "tags": [ "Device Self" ], "x-sdk-method": "getMe", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Device self record", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "organisationId": { "type": "string" }, "accountId": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "id", "name", "type", "organisationId", "accountId", "location" ] }, "roles": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "roleId": { "type": "string" } }, "required": [ "accountId", "roleId" ] } }, "config": { "type": "object", "properties": { "corsAllowlist": { "type": "array", "items": { "type": "string" } }, "localHostname": { "type": [ "string", "null" ] } }, "required": [ "corsAllowlist", "localHostname" ] } }, "required": [ "device", "roles", "config" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/heartbeat": { "post": { "summary": "Send a device heartbeat", "operationId": "deviceHeartbeat", "description": "Reports presence + peripheral status; returns hints (commandsPending, cert renewal, JWKS version).", "tags": [ "Device Self" ], "x-sdk-method": "heartbeat", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "appVersion": { "type": "string" }, "localPort": { "type": "number" }, "lanAddresses": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "interface": { "type": "string" } }, "required": [ "ip", "interface" ] } }, "peripheralStatuses": { "type": "array", "items": { "type": "object", "properties": { "clientKey": { "type": "string" }, "status": { "type": "object", "additionalProperties": {} } }, "required": [ "clientKey", "status" ] } } } } } } }, "responses": { "200": { "description": "Heartbeat acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverTime": { "type": "string" }, "commandsPending": { "type": "number" }, "certificateRenewalDue": { "type": "boolean" }, "jwksVersion": { "type": "number" } }, "required": [ "serverTime", "commandsPending", "certificateRenewalDue", "jwksVersion" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/peripherals": { "put": { "summary": "Declare peripherals", "operationId": "declareDevicePeripherals", "description": "Full-replacement declaration of the relay’s peripherals; returns the stable device id per clientKey.", "tags": [ "Device Self" ], "x-sdk-method": "declarePeripherals", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "peripherals": { "type": "array", "items": { "type": "object", "properties": { "clientKey": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "attachment": { "type": "string", "enum": [ "child", "routed" ] }, "vendor": { "type": "string" }, "model": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": {} }, "address": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number" } }, "required": [ "host", "port" ] }, "provider": { "type": "string" } }, "required": [ "clientKey", "kind", "name" ] } } }, "required": [ "peripherals" ] } } } }, "responses": { "200": { "description": "Peripherals registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "peripherals": { "type": "array", "items": { "type": "object", "properties": { "clientKey": { "type": "string" }, "deviceId": { "type": "string" } }, "required": [ "clientKey", "deviceId" ] } } }, "required": [ "peripherals" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/commands": { "get": { "summary": "Long-poll for commands", "operationId": "fetchDeviceCommands", "description": "Holds up to `wait` seconds (max 25) and returns pending commands, marking them delivered.", "tags": [ "Device Self" ], "x-sdk-method": "fetchCommands", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "number" }, "required": false, "name": "wait", "in": "query" } ], "responses": { "200": { "description": "Pending commands", "content": { "application/json": { "schema": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "peripheralId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "payload", "peripheralId", "expiresAt", "createdAt" ] } } }, "required": [ "commands" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/commands/{commandId}/progress": { "post": { "summary": "Report command progress", "operationId": "reportCommandProgress", "description": "Optional in-flight progress update (e.g. payment terminal awaiting card).", "tags": [ "Device Self" ], "x-sdk-method": "reportProgress", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "commandId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "progress": { "type": "object", "additionalProperties": {} } }, "required": [ "progress" ] } } } }, "responses": { "200": { "description": "Progress recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/commands/{commandId}/result": { "post": { "summary": "Report command result", "operationId": "reportCommandResult", "description": "Terminal result (completed|failed). Idempotent - the first terminal result wins.", "tags": [ "Device Self" ], "x-sdk-method": "reportResult", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "commandId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] }, "result": { "type": "object", "additionalProperties": {} } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Result recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/events": { "post": { "summary": "Upload device events", "operationId": "ingestDeviceEvents", "description": "Batch (≤500) idempotent upload of device-operational events; per-item accepted|duplicate.", "tags": [ "Device Self" ], "x-sdk-method": "ingestEvents", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "occurredAt": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "occurredAt" ] } } }, "required": [ "events" ] } } } }, "responses": { "200": { "description": "Ingest results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "accepted", "duplicate" ] } }, "required": [ "id", "outcome" ] } } }, "required": [ "results" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/me/certificate": { "get": { "summary": "Get local TLS certificate", "operationId": "getDeviceCertificate", "description": "Fetch (or trigger issuance of) the device’s local-control-plane TLS cert + key.", "tags": [ "Device Self" ], "x-sdk-method": "getCertificate", "x-parent-resource": "Device Self", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Certificate bundle", "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string" }, "certPem": { "type": "string" }, "privateKeyPem": { "type": "string" }, "notAfter": { "type": "string" } }, "required": [ "hostname", "certPem", "privateKeyPem", "notAfter" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/printers": { "get": { "summary": "List printers", "operationId": "listPrinters", "description": "Org-wide list of printer peripherals with status + capabilities, for the print-target picker.", "tags": [ "Devices" ], "x-sdk-method": "printers", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Printers", "content": { "application/json": { "schema": { "type": "object", "properties": { "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "online": { "type": "boolean" }, "paperOut": { "type": "boolean" }, "detached": { "type": "boolean" }, "capabilities": { "type": [ "object", "null" ], "additionalProperties": {} }, "hostDeviceId": { "type": [ "string", "null" ] }, "hostName": { "type": [ "string", "null" ] }, "accountId": { "type": "string" } }, "required": [ "id", "name", "location", "online", "paperOut", "detached", "capabilities", "hostDeviceId", "hostName", "accountId" ] } } }, "required": [ "printers" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/media-catalog": { "get": { "summary": "Print capability & standard-media catalog", "operationId": "getDeviceMediaCatalog", "description": "The canonical print capabilities and standard media sizes designs are authored against.", "tags": [ "Devices" ], "x-sdk-method": "mediaCatalog", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Media catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "mediaKind": { "type": "string" } }, "required": [ "id", "label", "mediaKind" ] } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "capability": { "type": "string" }, "label": { "type": "string" }, "widthMm": { "type": "number" }, "heightMm": { "type": "number" }, "continuous": { "type": "boolean" } }, "required": [ "id", "capability", "label", "widthMm", "continuous" ] } } }, "required": [ "capabilities", "media" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices": { "get": { "summary": "List devices", "operationId": "listDevices", "description": "List top-level devices (relays/scanners/kiosks) for the organisation.", "tags": [ "Devices" ], "x-sdk-method": "list", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 24 }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "maxLength": 32 }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "revoked" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "unknown", "online", "offline" ] }, "required": false, "name": "connectivity", "in": "query" }, { "schema": { "type": "string", "maxLength": 24 }, "required": false, "name": "locationId", "in": "query" } ], "responses": { "200": { "description": "Devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "connectivity": { "type": "string" }, "accountId": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "hostDeviceId": { "type": [ "string", "null" ] }, "attachment": { "type": [ "string", "null" ] }, "clientKey": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "capabilities": { "type": [ "object", "null" ], "additionalProperties": {} }, "liveStatus": { "type": [ "object", "null" ], "additionalProperties": {} }, "platform": { "type": [ "object", "null" ], "additionalProperties": {} }, "appVersion": { "type": [ "string", "null" ] }, "local": { "type": [ "object", "null" ], "properties": { "hostname": { "type": [ "string", "null" ] }, "port": { "type": [ "number", "null" ] } }, "required": [ "hostname", "port" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "online": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "peripherals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "id", "name", "type", "status", "connectivity", "accountId", "location", "hostDeviceId", "attachment", "clientKey", "vendor", "model", "capabilities", "liveStatus", "platform", "appVersion", "local", "lastSeenAt", "online", "createdAt", "updatedAt" ] } } }, "required": [ "devices" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}": { "get": { "summary": "Get device", "operationId": "getDevice", "description": "Get a device with its peripherals and live status.", "tags": [ "Devices" ], "x-sdk-method": "get", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "Device", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "connectivity": { "type": "string" }, "accountId": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "hostDeviceId": { "type": [ "string", "null" ] }, "attachment": { "type": [ "string", "null" ] }, "clientKey": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "capabilities": { "type": [ "object", "null" ], "additionalProperties": {} }, "liveStatus": { "type": [ "object", "null" ], "additionalProperties": {} }, "platform": { "type": [ "object", "null" ], "additionalProperties": {} }, "appVersion": { "type": [ "string", "null" ] }, "local": { "type": [ "object", "null" ], "properties": { "hostname": { "type": [ "string", "null" ] }, "port": { "type": [ "number", "null" ] } }, "required": [ "hostname", "port" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "online": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "peripherals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "id", "name", "type", "status", "connectivity", "accountId", "location", "hostDeviceId", "attachment", "clientKey", "vendor", "model", "capabilities", "liveStatus", "platform", "appVersion", "local", "lastSeenAt", "online", "createdAt", "updatedAt" ] } }, "required": [ "device" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update device", "operationId": "updateDevice", "description": "Rename or relocate a device.", "tags": [ "Devices" ], "x-sdk-method": "update", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "locationId": { "type": [ "string", "null" ], "maxLength": 24 } } } } } }, "responses": { "200": { "description": "Device updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "connectivity": { "type": "string" }, "accountId": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "hostDeviceId": { "type": [ "string", "null" ] }, "attachment": { "type": [ "string", "null" ] }, "clientKey": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "capabilities": { "type": [ "object", "null" ], "additionalProperties": {} }, "liveStatus": { "type": [ "object", "null" ], "additionalProperties": {} }, "platform": { "type": [ "object", "null" ], "additionalProperties": {} }, "appVersion": { "type": [ "string", "null" ] }, "local": { "type": [ "object", "null" ], "properties": { "hostname": { "type": [ "string", "null" ] }, "port": { "type": [ "number", "null" ] } }, "required": [ "hostname", "port" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "online": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "peripherals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "id", "name", "type", "status", "connectivity", "accountId", "location", "hostDeviceId", "attachment", "clientKey", "vendor", "model", "capabilities", "liveStatus", "platform", "appVersion", "local", "lastSeenAt", "online", "createdAt", "updatedAt" ] } }, "required": [ "device" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete device", "operationId": "deleteDevice", "description": "Soft-delete a revoked device.", "tags": [ "Devices" ], "x-sdk-method": "delete", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "Device deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/revoke": { "post": { "summary": "Revoke device", "operationId": "revokeDevice", "description": "Revoke a device and kill its credentials immediately.", "tags": [ "Devices" ], "x-sdk-method": "revoke", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "Device revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "connectivity": { "type": "string" }, "accountId": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "hostDeviceId": { "type": [ "string", "null" ] }, "attachment": { "type": [ "string", "null" ] }, "clientKey": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "capabilities": { "type": [ "object", "null" ], "additionalProperties": {} }, "liveStatus": { "type": [ "object", "null" ], "additionalProperties": {} }, "platform": { "type": [ "object", "null" ], "additionalProperties": {} }, "appVersion": { "type": [ "string", "null" ] }, "local": { "type": [ "object", "null" ], "properties": { "hostname": { "type": [ "string", "null" ] }, "port": { "type": [ "number", "null" ] } }, "required": [ "hostname", "port" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "online": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "peripherals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "id", "name", "type", "status", "connectivity", "accountId", "location", "hostDeviceId", "attachment", "clientKey", "vendor", "model", "capabilities", "liveStatus", "platform", "appVersion", "local", "lastSeenAt", "online", "createdAt", "updatedAt" ] } }, "required": [ "device" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/roles": { "put": { "summary": "Assign device roles", "operationId": "assignDeviceRoles", "description": "Replace a device’s account-role assignments.", "tags": [ "Devices" ], "x-sdk-method": "assignRoles", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountRoles": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 24 }, "roleId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "accountId", "roleId" ] } } }, "required": [ "accountRoles" ] } } } }, "responses": { "200": { "description": "Roles assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "roleId": { "type": "string" } }, "required": [ "accountId", "roleId" ] } } }, "required": [ "roles" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/credentials/rotate": { "post": { "summary": "Rotate device credential", "operationId": "rotateDeviceCredential", "description": "Issue a new device secret; existing credentials grace-expire.", "tags": [ "Devices" ], "x-sdk-method": "rotateCredential", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "graceSeconds": { "type": "integer", "minimum": 0, "maximum": 604800 } } } } } }, "responses": { "201": { "description": "Credential rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialId": { "type": "string" }, "deviceSecret": { "type": "string" } }, "required": [ "credentialId", "deviceSecret" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/commands": { "post": { "summary": "Dispatch a command", "operationId": "dispatchDeviceCommand", "description": "Queue a command for a device or one of its peripherals. Idempotent on Idempotency-Key.", "tags": [ "Devices" ], "x-sdk-method": "dispatchCommand", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "peripheralId": { "type": "string" }, "idempotencyKey": { "type": "string" } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Command dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "peripheralId": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "idempotencyKey": { "type": [ "string", "null" ] }, "progress": { "type": [ "object", "null" ], "additionalProperties": {} }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "createdBy": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "deviceId", "peripheralId", "type", "status", "payload", "idempotencyKey", "progress", "result", "createdBy", "expiresAt", "createdAt", "deliveredAt", "completedAt" ] } }, "required": [ "command" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List device commands", "operationId": "listDeviceCommands", "description": "Command history for a device (most recent first).", "tags": [ "Devices" ], "x-sdk-method": "listCommands", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "Commands", "content": { "application/json": { "schema": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "peripheralId": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "idempotencyKey": { "type": [ "string", "null" ] }, "progress": { "type": [ "object", "null" ], "additionalProperties": {} }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "createdBy": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "deviceId", "peripheralId", "type", "status", "payload", "idempotencyKey", "progress", "result", "createdBy", "expiresAt", "createdAt", "deliveredAt", "completedAt" ] } } }, "required": [ "commands" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/commands/{commandId}": { "get": { "summary": "Get a command", "operationId": "getDeviceCommand", "description": "Get a single command’s status/result by id (poll for completion).", "tags": [ "Devices" ], "x-sdk-method": "getCommand", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "commandId", "in": "path" } ], "responses": { "200": { "description": "Command", "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "peripheralId": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "idempotencyKey": { "type": [ "string", "null" ] }, "progress": { "type": [ "object", "null" ], "additionalProperties": {} }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "createdBy": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "deviceId", "peripheralId", "type", "status", "payload", "idempotencyKey", "progress", "result", "createdBy", "expiresAt", "createdAt", "deliveredAt", "completedAt" ] } }, "required": [ "command" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/events": { "get": { "summary": "List device events", "operationId": "listDeviceEvents", "description": "The device-operational event log (most recent first).", "tags": [ "Devices" ], "x-sdk-method": "listEvents", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "responses": { "200": { "description": "Device events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {} }, "occurredAt": { "type": "string" }, "receivedAt": { "type": "string" } }, "required": [ "id", "type", "payload", "occurredAt", "receivedAt" ] } } }, "required": [ "events" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/devices/{deviceId}/local-tokens": { "post": { "summary": "Mint a Local Command Token", "operationId": "mintLocalToken", "description": "Mint a short-lived, capability-scoped token a browser POS presents to the device’s local control plane.", "tags": [ "Devices" ], "x-sdk-method": "mintLocalToken", "x-parent-resource": "Devices", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dvid_[a-zA-Z0-9]+$" }, "required": true, "name": "deviceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedCommandTypes": { "type": "array", "items": { "type": "string" } }, "ttlSeconds": { "type": "number" }, "accountIds": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Local command token", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "tokenId": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "token", "tokenId", "expiresAt" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/locations": { "post": { "summary": "Create location", "operationId": "createLocation", "tags": [ "Locations" ], "x-sdk-method": "create", "x-parent-resource": "Locations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 24 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 } }, "required": [ "accountId", "name" ] } } } }, "responses": { "201": { "description": "Location created", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "accountId", "createdAt", "updatedAt" ] } }, "required": [ "location" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List locations", "operationId": "listLocations", "tags": [ "Locations" ], "x-sdk-method": "list", "x-parent-resource": "Locations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Locations", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "accountId", "createdAt", "updatedAt" ] } } }, "required": [ "locations" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/locations/{locationId}": { "get": { "summary": "Get location", "operationId": "getLocation", "tags": [ "Locations" ], "x-sdk-method": "get", "x-parent-resource": "Locations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^loc_[a-zA-Z0-9]+$" }, "required": true, "name": "locationId", "in": "path" } ], "responses": { "200": { "description": "Location", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "accountId", "createdAt", "updatedAt" ] } }, "required": [ "location" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update location", "operationId": "updateLocation", "tags": [ "Locations" ], "x-sdk-method": "update", "x-parent-resource": "Locations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^loc_[a-zA-Z0-9]+$" }, "required": true, "name": "locationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Location updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "accountId", "createdAt", "updatedAt" ] } }, "required": [ "location" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete location", "operationId": "deleteLocation", "tags": [ "Locations" ], "x-sdk-method": "delete", "x-parent-resource": "Locations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^loc_[a-zA-Z0-9]+$" }, "required": true, "name": "locationId", "in": "path" } ], "responses": { "200": { "description": "Location deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/summary": { "get": { "summary": "Sales summary KPIs", "operationId": "getReportsSummary", "description": "Headline realised-sales KPIs (gross, net-to-organiser, fees, tax, tickets, AOV) per currency. Money is integer minor units. Tenant- and account-scoped via the analytics principal.", "tags": [ "Reports" ], "x-sdk-method": "summary", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "eventId", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "Summary retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportSummaryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/timeseries": { "get": { "summary": "Sales over time", "operationId": "getReportsTimeseries", "description": "Gross revenue and tickets sold bucketed by day/week/month, per currency.", "tags": [ "Reports" ], "x-sdk-method": "timeseries", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "eventId", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "required": false, "name": "granularity", "in": "query" } ], "responses": { "200": { "description": "Timeseries retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTimeseriesResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/inventory": { "get": { "summary": "Inventory sell-through", "operationId": "getReportsInventory", "description": "Current sell-through and utilisation per occurrence.", "tags": [ "Reports" ], "x-sdk-method": "inventory", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "eventId", "in": "query" } ], "responses": { "200": { "description": "Inventory summary retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportInventoryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/meta": { "get": { "summary": "Semantic model", "operationId": "getReportsMeta", "description": "The semantic model (data models, measures, dimensions) the caller may explore - drives the explorer pickers and grounds NL queries.", "tags": [ "Reports" ], "x-sdk-method": "meta", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Semantic model retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMetaResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/query": { "post": { "summary": "Run an ad-hoc query", "operationId": "runReportsQuery", "description": "Execute an arbitrary (validated + guarded) Insights query. Tenant- and account-scoped via the analytics principal; data models/members restricted and cost capped.", "tags": [ "Reports" ], "x-sdk-method": "query", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Query executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportQueryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/saved": { "get": { "summary": "List saved reports", "operationId": "listSavedReports", "description": "List the saved reports the caller may see in their organisation.", "tags": [ "Reports" ], "x-sdk-method": "savedList", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Saved reports retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReportListResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create a saved report", "operationId": "createSavedReport", "description": "Persist a cube query + viz + slicer params as a reusable report.", "tags": [ "Reports" ], "x-sdk-method": "savedCreate", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "accountId": { "type": "string" }, "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } }, "params": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "timeRange", "groupBy", "filter", "compare" ] }, "member": { "type": "string" }, "label": { "type": "string" }, "allowed": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind" ] }, "maxItems": 20 }, "viz": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table", "line", "bar", "area", "pie", "kpi" ] }, "x": { "type": "string" }, "y": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "series": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "name", "query" ] } } } }, "responses": { "201": { "description": "Saved report created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReportResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/saved/{id}": { "get": { "summary": "Get a saved report", "operationId": "getSavedReport", "tags": [ "Reports" ], "x-sdk-method": "savedGet", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Saved report retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReportResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update a saved report", "operationId": "updateSavedReport", "tags": [ "Reports" ], "x-sdk-method": "savedUpdate", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "accountId": { "type": "string" }, "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } }, "params": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "timeRange", "groupBy", "filter", "compare" ] }, "member": { "type": "string" }, "label": { "type": "string" }, "allowed": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind" ] }, "maxItems": 20 }, "viz": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table", "line", "bar", "area", "pie", "kpi" ] }, "x": { "type": "string" }, "y": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "series": { "type": "string" } }, "required": [ "type" ] } } } } } }, "responses": { "200": { "description": "Saved report updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReportResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete a saved report", "operationId": "deleteSavedReport", "tags": [ "Reports" ], "x-sdk-method": "savedDelete", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Saved report deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReportDeleteResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/saved/{id}/run": { "post": { "summary": "Run a saved report", "operationId": "runSavedReport", "description": "Execute a saved report, optionally merging slicer overrides onto its base query (re-validated + re-scoped).", "tags": [ "Reports" ], "x-sdk-method": "savedRun", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "overrides": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Saved report executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportQueryResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/dashboards": { "get": { "summary": "List dashboards", "operationId": "listDashboards", "tags": [ "Reports" ], "x-sdk-method": "dashboardList", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Dashboards retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardListResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "summary": "Create a dashboard", "operationId": "createDashboard", "tags": [ "Reports" ], "x-sdk-method": "dashboardCreate", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "accountId": { "type": "string" }, "layout": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string" }, "title": { "type": "string", "maxLength": 255 }, "reportId": { "type": "string" }, "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } }, "viz": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table", "line", "bar", "area", "pie", "kpi" ] }, "x": { "type": "string" }, "y": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "series": { "type": "string" } }, "required": [ "type" ] }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "h": { "type": "integer", "minimum": 1, "maximum": 24 } }, "required": [ "tileId", "x", "y", "w", "h" ] }, "maxItems": 50 }, "globalFilters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "control": { "type": "string", "enum": [ "dateRange", "select", "multiselect" ] }, "member": { "type": "string" }, "members": { "type": "object", "additionalProperties": { "type": "string" } }, "default": {} }, "required": [ "key", "label", "control" ] }, "maxItems": 20 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Dashboard created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/dashboards/{id}": { "get": { "summary": "Get a dashboard", "operationId": "getDashboard", "tags": [ "Reports" ], "x-sdk-method": "dashboardGet", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Dashboard retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update a dashboard", "operationId": "updateDashboard", "tags": [ "Reports" ], "x-sdk-method": "dashboardUpdate", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "accountId": { "type": "string" }, "layout": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string" }, "title": { "type": "string", "maxLength": 255 }, "reportId": { "type": "string" }, "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 25 }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "dateRange": { "anyOf": [ { "type": "string" }, { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } ] } }, "required": [ "dimension" ] }, "maxItems": 5 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "member", "operator" ] }, "maxItems": 30 }, "segments": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "order": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string", "enum": [ "asc", "desc" ] } ] } } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "offset": { "type": "integer", "minimum": 0 }, "timezone": { "type": "string" } } }, "viz": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table", "line", "bar", "area", "pie", "kpi" ] }, "x": { "type": "string" }, "y": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "series": { "type": "string" } }, "required": [ "type" ] }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "h": { "type": "integer", "minimum": 1, "maximum": 24 } }, "required": [ "tileId", "x", "y", "w", "h" ] }, "maxItems": 50 }, "globalFilters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "control": { "type": "string", "enum": [ "dateRange", "select", "multiselect" ] }, "member": { "type": "string" }, "members": { "type": "object", "additionalProperties": { "type": "string" } }, "default": {} }, "required": [ "key", "label", "control" ] }, "maxItems": 20 } } } } } }, "responses": { "200": { "description": "Dashboard updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete a dashboard", "operationId": "deleteDashboard", "tags": [ "Reports" ], "x-sdk-method": "dashboardDelete", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Dashboard deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDeleteResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/templates": { "get": { "summary": "List standard templates", "operationId": "listReportTemplates", "description": "The standard library of report/dashboard templates that can be installed.", "tags": [ "Reports" ], "x-sdk-method": "templateList", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Templates retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateListResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/reports/templates/{key}/install": { "post": { "summary": "Install a template", "operationId": "installReportTemplate", "description": "Clone a standard template into the org: creates its saved reports + a dashboard the org then owns.", "tags": [ "Reports" ], "x-sdk-method": "templateInstall", "x-parent-resource": "Reports", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "name": "key", "in": "path" } ], "responses": { "201": { "description": "Template installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-endpoints": { "post": { "summary": "Create a webhook endpoint", "operationId": "createWebhookEndpoint", "description": "Register a URL to receive signed POSTs for the chosen public event types. The signing `secret` is returned ONCE in this response and is never retrievable again.", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "create", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" } } } }, "responses": { "201": { "description": "Endpoint created", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "auto_disabled" ] }, "version": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "accountId", "url", "description", "eventTypes", "status", "version", "source", "createdAt", "updatedAt" ] }, "secret": { "type": "string" } }, "required": [ "endpoint", "secret" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "get": { "summary": "List webhook endpoints", "operationId": "listWebhookEndpoints", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "list", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^acc_[a-zA-Z0-9]+$" }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "auto_disabled" ] }, "version": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "accountId", "url", "description", "eventTypes", "status", "version", "source", "createdAt", "updatedAt" ] } } }, "required": [ "endpoints" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-endpoints/{endpointId}": { "get": { "summary": "Get a webhook endpoint", "operationId": "getWebhookEndpoint", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "get", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whk_[a-zA-Z0-9]+$" }, "required": true, "name": "endpointId", "in": "path" } ], "responses": { "200": { "description": "Endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "auto_disabled" ] }, "version": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "accountId", "url", "description", "eventTypes", "status", "version", "source", "createdAt", "updatedAt" ] } }, "required": [ "endpoint" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "patch": { "summary": "Update a webhook endpoint", "operationId": "updateWebhookEndpoint", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "update", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whk_[a-zA-Z0-9]+$" }, "required": true, "name": "endpointId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpoint" } } } }, "responses": { "200": { "description": "Updated endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "auto_disabled" ] }, "version": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "accountId", "url", "description", "eventTypes", "status", "version", "source", "createdAt", "updatedAt" ] } }, "required": [ "endpoint" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } }, "delete": { "summary": "Delete a webhook endpoint", "operationId": "deleteWebhookEndpoint", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "delete", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whk_[a-zA-Z0-9]+$" }, "required": true, "name": "endpointId", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-endpoints/{endpointId}/test": { "post": { "summary": "Send a test delivery", "operationId": "testWebhookEndpoint", "description": "Enqueue a sample signed delivery to the endpoint to verify connectivity.", "tags": [ "Webhook Endpoints" ], "x-sdk-method": "test", "x-parent-resource": "Webhook Endpoints", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whk_[a-zA-Z0-9]+$" }, "required": true, "name": "endpointId", "in": "path" } ], "responses": { "202": { "description": "Test delivery enqueued", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string" } }, "required": [ "deliveryId" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-event-types": { "get": { "summary": "List subscribable webhook event types", "operationId": "listWebhookEventTypes", "tags": [ "Webhook Event Types" ], "x-sdk-method": "list", "x-parent-resource": "Webhook Event Types", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type", "description" ] } } }, "required": [ "eventTypes" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-inbound": { "get": { "summary": "List recent inbound webhook events (ingress log)", "operationId": "listInboundWebhooks", "tags": [ "Webhook Deliveries" ], "x-sdk-method": "listInbound", "x-parent-resource": "Webhook Deliveries", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Inbound events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "eventType": { "type": [ "string", "null" ] }, "normalisedType": { "type": [ "string", "null" ] }, "organisationId": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" }, "status": { "type": "string", "enum": [ "received", "processed", "failed" ] }, "attempts": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "receivedAt": { "type": "string" }, "processedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "provider", "eventType", "normalisedType", "organisationId", "verified", "status", "attempts", "error", "receivedAt", "processedAt" ] } } }, "required": [ "events" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-deliveries": { "get": { "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "description": "The delivery log - every attempt, its status, response and retry schedule.", "tags": [ "Webhook Deliveries" ], "x-sdk-method": "list", "x-parent-resource": "Webhook Deliveries", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whk_[a-zA-Z0-9]+$" }, "required": false, "name": "endpointId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventType": { "type": "string" }, "sourceEventId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "number" }, "responseStatus": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ] }, "lastAttemptAt": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "endpointId", "eventType", "sourceEventId", "status", "attempts", "responseStatus", "error", "nextAttemptAt", "lastAttemptAt", "deliveredAt", "createdAt" ] } } }, "required": [ "deliveries" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhook-deliveries/{deliveryId}": { "get": { "summary": "Get a webhook delivery", "operationId": "getWebhookDelivery", "tags": [ "Webhook Deliveries" ], "x-sdk-method": "get", "x-parent-resource": "Webhook Deliveries", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^whd_[a-zA-Z0-9]+$" }, "required": true, "name": "deliveryId", "in": "path" } ], "responses": { "200": { "description": "Delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventType": { "type": "string" }, "sourceEventId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "number" }, "responseStatus": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ] }, "lastAttemptAt": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "endpointId", "eventType", "sourceEventId", "status", "attempts", "responseStatus", "error", "nextAttemptAt", "lastAttemptAt", "deliveredAt", "createdAt" ] } }, "required": [ "delivery" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/integrations": { "get": { "summary": "List the integration marketplace", "operationId": "listIntegrations", "description": "The marketplace catalogue (connected apps + provider integrations) with this org’s status for each.", "tags": [ "Integrations" ], "x-sdk-method": "list", "x-parent-resource": "Integrations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "connected_app", "provider" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "logoUri": { "type": [ "string", "null" ] }, "available": { "type": "boolean" }, "status": { "type": "string", "enum": [ "connected", "configured", "not_connected", "coming_soon" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": [ "string", "null" ] }, "capability": { "type": "string" }, "configResource": { "type": "string" } }, "required": [ "id", "kind", "name", "description", "category", "logoUri", "available", "status" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "order": { "type": "number" }, "blurb": { "type": "string" } }, "required": [ "id", "label", "order", "blurb" ] } } }, "required": [ "integrations", "categories" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/integrations/connected-apps": { "get": { "summary": "List connected OAuth apps for the org", "operationId": "listConnectedApps", "tags": [ "Integrations" ], "x-sdk-method": "listConnectedApps", "x-parent-resource": "Integrations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "responses": { "200": { "description": "Connected apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectedApps": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "connected", "revoked" ] }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] } }, "required": [ "clientId", "scopes", "status", "firstSeenAt", "lastSeenAt", "revokedAt" ] } } }, "required": [ "connectedApps" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/integrations/{id}": { "get": { "summary": "Get an integration", "operationId": "getIntegration", "tags": [ "Integrations" ], "x-sdk-method": "get", "x-parent-resource": "Integrations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Integration", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "connected_app", "provider" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "logoUri": { "type": [ "string", "null" ] }, "available": { "type": "boolean" }, "status": { "type": "string", "enum": [ "connected", "configured", "not_connected", "coming_soon" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": [ "string", "null" ] }, "capability": { "type": "string" }, "configResource": { "type": "string" } }, "required": [ "id", "kind", "name", "description", "category", "logoUri", "available", "status" ] } }, "required": [ "integration" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } }, "/integrations/{id}/connection": { "delete": { "summary": "Revoke a connected app", "operationId": "revokeIntegrationConnection", "tags": [ "Integrations" ], "x-sdk-method": "revokeConnection", "x-parent-resource": "Integrations", "x-tl-surface": "backstage", "security": [ { "bearerAuth": [], "orgHeader": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ] } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not Found - Resource not found" }, "500": { "description": "Internal Server Error" } } } } }, "webhooks": {} }